Forward convexUrl to Next.js Convex helpers

[JohnKesko]

Summary

• forward the configured convexUrl into preloadQuery, fetchQuery, fetchMutation, and fetchAction from the Next.js auth helper
• add a regression test covering all authenticated Next.js helper wrappers

Verification

• npm run test -- src/nextjs/index.test.ts
• npm run build

[vercel]

@JohnKesko is attempting to deploy a commit to the Convex Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

Pull request overview

This PR ensures the configured convexUrl is forwarded into the Convex Next.js helper calls made by the authenticated Better Auth wrappers, and adds a regression test to prevent future regressions.

Changes:

• Forward opts.convexUrl into preloadQuery, fetchQuery, fetchMutation, and fetchAction via the options object.
• Update internal helper typing to include the url option alongside token.
• Add a Vitest regression test verifying url is passed for all authenticated Next.js helper wrappers.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/nextjs/index.ts	Threads opts.convexUrl through to Convex Next.js helper options ({ token, url }).
src/nextjs/index.test.ts	Adds a regression test asserting all authenticated wrappers pass url (and token) to Convex helpers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: get-convex/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b50f672b-f6f9-4644-b12d-311bb1b581eb

📥 Commits

Reviewing files that changed from the base of the PR and between dc91191 and ec0c2aa.

📒 Files selected for processing (2)

• src/nextjs/index.test.ts
• src/nextjs/index.ts

---

📝 Walkthrough

Walkthrough

The changes update the Convex integration to forward the Convex URL alongside the authentication token through all query, mutation, and action calls. A corresponding test suite was added to verify that the convexBetterAuthNextJs instance correctly passes both the token and URL to the underlying Convex operations when auth methods are invoked.

Suggested reviewers

• erquhart

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: forwarding convexUrl to Next.js Convex helpers, which is directly supported by modifications to getArgsAndOptions and auth wrapper methods.
Description check	✅ Passed	The description is directly related to the changeset, detailing the forwarding of convexUrl into helper functions and the addition of a regression test that match the code changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[erquhart]

@JohnKesko you can access your Convex site url via process.env.CONVEX_SITE_URL in your functions, no need to pass it via args. Let me know if I'm missing something here.

[JohnKesko]

@erquhart

Yes, CONVEX_SITE_URL works for the Better Auth/site URL part. I should have explained the context better in the PR.

The bit I ran into was the separate Convex client/deployment URL.

convexBetterAuthNextJs already takes a convexUrl but the Nextjs helper wrappers weren’t passing that through to preloadQuery, fetchQuery, fetchMutation, or fetchAction.

Because of that, those helpers fall back to NEXT_PUBLIC_CONVEX_URL. So this PR just makes the explicit convexUrl option work for those operations as well which is nice if someone wants to use different env var names or configure the URLs directly.

For example, my setup looks roughly like this:

import { convexBetterAuthNextJs } from "@convex-dev/better-auth/nextjs";

if (!process.env.NEXT_PUBLIC_CLIENT_URL) {
  throw new Error("NEXT_PUBLIC_CLIENT_URL environment variable is not set");
}

if (!process.env.NEXT_PUBLIC_API_URL) {
  throw new Error("NEXT_PUBLIC_API_URL environment variable is not set");
}

export const {
  handler,
  preloadAuthQuery,
  isAuthenticated,
  getToken,
  fetchAuthQuery,
  fetchAuthMutation,
  fetchAuthAction,
} = convexBetterAuthNextJs({
    convexUrl: process.env.NEXT_PUBLIC_CLIENT_URL, // .convex.cloud, this is what the PR passes through
    convexSiteUrl: process.env.NEXT_PUBLIC_API_URL, // .convex.site, already used by the auth handler
});

[JohnKesko]

@erquhart Is this something you will consider?