Installation

Clone the repository

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

If GitHub says the repository doesn't exist, check that you are signed in with the account that has access.

Install dependencies

Use Node.js 24 (the version in .nvmrc; package.json engines requires >=24) and let corepack select pnpm 10.33.0 from the packageManager field.

corepack enable
pnpm install

Create and select the local Convex backend

Copy the example env file first, then create and select the local deployment:

cp .env.local.example .env.local
pnpm db:local:init
pnpm db:local:select

db:local:init runs convex init with CONVEX_AGENT_MODE=anonymous, so no Convex login is needed. db:local:select runs convex deployment select local and fills in CONVEX_DEPLOYMENT, VITE_CONVEX_URL and CONVEX_SITE_URL in .env.local at the repository root. The backend state (rows, storage, schedules, function execution) lives in .convex/, which is gitignored.

Copying the example file first matters. When .env.local already contains a VITE_CONVEX_URL line, the CLI updates it. When the file does not exist, the CLI creates it with CONVEX_URL instead, because Vite is not a root dependency, and you have to add VITE_CONVEX_URL yourself. The dev:local guard accepts either name for its loopback check, but stops with a message telling you to add VITE_CONVEX_URL=http://127.0.0.1:3210 if only CONVEX_URL is present, because the web app reads the VITE_ name.

After the select step, the first lines of .env.local should look like this:

CONVEX_DEPLOYMENT=local:nextbase
VITE_CONVEX_URL=http://127.0.0.1:3210
CONVEX_SITE_URL=http://127.0.0.1:3211
APP_URL=http://localhost:3000

APP_URL is never generated; it comes from the example file. The example also sets VITE_ADMIN_APP_URL=http://localhost:3002 for the admin app link and MCP_APP_URL=http://localhost:3000 for the MCP consent page.

Configure the admin app

The admin app has its own env file because apps/admin/vite.config.ts sets envDir: ".". Copy its example and point it at the local backend:

cp apps/admin/.env.local.example apps/admin/.env.local

VITE_CONVEX_URL=http://127.0.0.1:3210
VITE_WEB_APP_URL=http://localhost:3000
VITE_OAUTH_PROVIDERS=

The example ships with a cloud placeholder for VITE_CONVEX_URL; replace it with the same local URL the web app uses. VITE_WEB_APP_URL is where impersonation handoffs and the "Open web app" link go.

Set up Convex Auth

pnpm auth:setup

This runs the @convex-dev/auth CLI against the selected deployment. It configures the auth signing keys (JWT_PRIVATE_KEY and JWKS) and SITE_URL in that deployment's environment. Password sign-in works after this step. Run it again if you create a new local deployment.

So the admin app can sign in on its own origin, also set the admin origin in the local deployment:

pnpm convex env set ADMIN_SITE_URL http://localhost:3002

Start the dev servers

pnpm dev:local

dev:local runs the guard, then starts four processes with concurrently: convex dev (local backend on http://127.0.0.1:3210, HTTP actions on http://127.0.0.1:3211), the web app, the admin app and the React Email preview server.

To run only the admin app, use pnpm dev:admin. Keep the Convex process running while you use either app.

Seed reference data (optional)

In a second terminal:

pnpm db:seed

This runs dev/seed:seed, which inserts the product row in appSettings (product name and support email) once. It is idempotent.

Create your account and workspace

Open http://localhost:3000/sign-up and create an account with a name, email and password. The kit then sends a verification code and takes you to /update-password?mode=verify to enter it.

After signing in you land on /onboarding, complete your profile and create a workspace. Then add a project from the workspace's projects page so you have data to test with.

Verify the setup

Run the quality gates from the repository root:

pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build

pnpm test runs Vitest in each workspace (Convex functions use convex-test). pnpm test:e2e runs Playwright against http://127.0.0.1:3000; without PLAYWRIGHT_BASE_URL it starts its own local Convex backend and web server. Install the browser first with pnpm --filter @nextbase/web exec playwright install --with-deps chromium.