Next.js Setup

This guide installs Auth UI (self-hosted user & organization management) in a Next.js + Convex app.
All UI code is copied into your project (shadcn-style) from Convex-Better-Auth-UI, so you own every component and flow.

Time estimate

  • New projects: typically ~5 minutes.
  • Existing projects: depends on your current setup and may require additional integration work.

Use this guide for:

  • New projects: follow everything from top to bottom.
  • Existing projects: skip the Next.js scaffold and start with Install Auth UI.

1. (Optional) Create a new Next.js app

If you’re starting a fresh App Router project:

This keeps the scaffold non-interactive, disables React Compiler, and includes the generated AGENTS.md.

2. Install Auth UI (CLI)

The CLI scaffolds all required Auth files (Convex functions, React components, themes, route handlers, proxy, and server helpers) and keeps them up to date.

During jsrepo init @auth/nextjs:

  • Press Enter to accept all default paths.

The jsrepo add ... --yes part applies the generated changes and installs dependencies automatically. You can review everything afterwards through Git.

3. Configure Convex

Set up your dev deployment

Running npx convex dev will:

  • Log you into Convex
  • Create a project
  • Generate the deployment + URLs
  • Keep syncing your functions while developing

Add Convex environment variables

Generate the secret for encryption and hashing:

Allow your local development hosts and set the canonical fallback URL:

BETTER_AUTH_ALLOWED_HOSTS is used for dynamic request URLs. BETTER_AUTH_FALLBACK_URL is used only when backend auth calls run without an incoming app request, such as Convex queries, mutations, triggers, scheduled functions, and device authorization.

If you need to force the protocol Better Auth should use when constructing URLs, you can also set:

In most setups this is optional. Better Auth can derive the protocol automatically from the request and proxy headers.

4. Run the app

Start the development server:

Your app is now ready to use with password sign-in. If you want to enable more auth features, continue with Configure Features.