Installation

Clone the repository

git clone https://github.com/usenextbase/nextjs-convex-starter.git
cd nextjs-convex-starter

If GitHub says the repository doesn't exist, sign in with the account that has access.

Install dependencies

corepack enable
pnpm install --frozen-lockfile

The root package.json pins pnpm@11.1.2, so Corepack installs the right version. ./setup.sh does the same two steps and first checks that node --version is a 24.x release.

pnpm install also runs fumadocs-mdx in apps/web to generate apps/web/.source/; don't edit that folder. The .claude/skills entry is a symlink to .agents/skills/, so on Windows run git config core.symlinks true before cloning.

Create the web env file

Copy the web example only if you don't already have a local file:

[ -f apps/web/.env.local ] || cp apps/web/.env.local.example apps/web/.env.local

Never overwrite an existing apps/web/.env.local. The Convex connection values at the top of the example (APP_ENV, NEXT_PUBLIC_CONVEX_URL, CONVEX_SITE_URL, CONVEX_DEPLOYMENT) are commented out and marked as generated: the next step writes them into this file and keeps everything else you have in it. Fill in the optional integrations (Stripe, Resend, PostHog, Unkey) as you enable them.

You do not need to create apps/admin/.env.local by hand; the bootstrap writes it. apps/admin/.env.local.example shows the admin app's own values if you want to prepare one.

The web example still lists Supabase keys, marked as legacy, for code paths that have not been ported yet; Convex itself does not read them. See environment variables for the full list.

Start the backend, the web app, the admin app and the email preview

pnpm dev

On the first launch the Convex CLI asks which deployment to use. Choose local development. You can also pre-select it with pnpm db:select-local, which runs convex deployment select local.

pnpm dev is convex dev --start '...'. It keeps the local Convex backend running, pushes the schema and functions, and after the first successful sync runs pnpm bootstrap:local followed by turbo run dev for the web, admin and @nextbase/email packages. The bootstrap script (scripts/bootstrap-convex-local.ts):

1. Reads the CLI-generated root .env.local (CONVEX_DEPLOYMENT, CONVEX_URL, CONVEX_SITE_URL) and refuses to continue unless the deployment name starts with local: or anonymous:.
2. Writes APP_ENV, NEXT_PUBLIC_SITE_URL, CONVEX_DEPLOYMENT, NEXT_PUBLIC_CONVEX_URL, CONVEX_SITE_URL, NEXT_PUBLIC_ADMIN_APP_URL and a generated REVALIDATE_SECRET into apps/web/.env.local.
3. Writes APP_ENV, NEXT_PUBLIC_SITE_URL=http://localhost:3002, NEXT_PUBLIC_WEB_APP_URL, NEXT_PUBLIC_CONVEX_URL, CONVEX_SITE_URL and the same REVALIDATE_SECRET into apps/admin/.env.local.
4. Generates JWT_PRIVATE_KEY and JWKS on the local backend if they are missing, and sets SITE_URL=http://localhost:3000, ADMIN_SITE_URL=http://localhost:3002 and APP_ENV=local there.
5. Runs convex run seed:seed, which is idempotent (tracked in the seedVersions table).

Keep this process running while you work. The web app is at http://localhost:3000, the admin app at http://localhost:3002 and the React Email preview at http://localhost:3001.

To run the pieces separately once a backend exists: pnpm convex:dev, pnpm dev:web, pnpm dev:admin, pnpm dev:email. pnpm convex:once pushes functions once and exits.

Find local emails

Auth emails are not delivered locally. With APP_ENV=local on the backend, apps/database/convex/auth.ts logs each verification or magic-link message as [local-auth-email] with the recipient, the code and the URL. convex dev tails backend logs, so the message appears in the pnpm dev terminal. Copy the code from there.

Two things to know:

• The password reset provider has no local branch. It always needs SITE_URL, AUTH_RESEND_KEY and AUTH_EMAIL_FROM on the backend, even locally (pnpm exec convex env set AUTH_RESEND_KEY re_xxx).
• Application emails sent by the Next.js server (for example invitations) use apps/web/src/utils/api-routes/utils.ts. In development they are posted to a Mailpit server at http://localhost:54324, which this kit does not start. Those sends fail until you run a Mailpit instance there or set USE_LOCAL_EMAIL to anything other than true together with a RESEND_API_KEY in apps/web/.env.local.

Check that everything works

pnpm verify:local

This runs lint, typecheck, the unit tests and a compile-mode next build of the web app. It copies any missing .env.local files from their examples first and does not need a cloud deployment. For a quicker loop use pnpm --filter database test (Vitest with convex-test), pnpm --filter web test or pnpm --filter admin test.

pnpm test-integration runs Playwright against a built app (pnpm build-and-test-integration builds first). Its helpers are still Supabase-era in places, so expect to adapt them.

Create an account and a workspace

Open http://localhost:3000/sign-up. Passwords need at least 10 characters. Enter the verification code from the [local-auth-email] log line, then complete onboarding: accept the terms, fill in your profile and create a workspace.

Add a project through the website so there is data to try with an agent.

Make yourself an application administrator

Every new account gets the user platform role. Promote your account with the internal platform:grantAdmin mutation, run from the repository root against the selected deployment:

pnpm exec convex run platform:grantAdmin '{"email":"you@example.com"}'

It is idempotent, refuses unknown or disabled accounts, and is an internalMutation, so it is never exposed over the client API. Then open http://localhost:3002/login, sign in with the same credentials and you land on /app-admin. Continue to agent connections to try the User and Admin MCP servers.