Installation
Run the TanStack + Supabase starter locally with its own Supabase project, then sign in and create a workspace.
This page walks through a local setup from an empty directory to a signed-in workspace. It follows the local Supabase per agent workflow, so each git worktree gets its own Supabase project. Read that page once; this page only shows the commands that are specific to this kit.
Clone the repository
git clone https://github.com/usenextbase/tanstack-supabase-starter.git
cd tanstack-supabase-starterIf GitHub says the repository does not exist, sign in with the account that has access.
Install dependencies
Use Node.js 24 (.nvmrc) and let Corepack pick pnpm 11.1.2 from the packageManager field.
corepack enable
pnpm installpnpm install also installs the Supabase CLI (pinned to 2.121.0) into apps/database, so every database command below runs through pnpm --filter database exec supabase.
Choose: one command or step by step
The repository ships a pnpm setup script (setup.sh) that does the rest of this page in one go: it runs pnpm install, copies apps/web/.env.example to apps/web/.env if that file is missing, starts the local Supabase project, writes its URL and keys into apps/web/.env and apps/admin/.env, and regenerates the database types.
pnpm setup
pnpm devIf that worked, skip to "Start the dev servers" below. The remaining steps show what the script does, which you need when you want to use --runtime native, set a different web port, or debug a failed start.
Create the env files
Copy the examples only if you have not created your own files yet.
[ -f apps/web/.env ] || cp apps/web/.env.example apps/web/.env
[ -f apps/admin/.env ] || cp apps/admin/.env.example apps/admin/.envThe web app defaults to APP_URL=http://localhost:3000 with HOST=0.0.0.0 and PORT=3000; the admin app defaults to APP_URL=http://localhost:3002, PORT=3002 and WEB_APP_URL=http://localhost:3000, which it uses for support sign-in links into the product. Every variable is described on environment variables.
Start the local Supabase project
pnpm db:startThis runs supabase start in apps/database. apps/database/supabase/config.toml enables the CLI stack engine ([experimental] stack = true), so there are no fixed service ports: the CLI picks free ports for this worktree's project. Pass the runtime explicitly when you need to, for example pnpm --filter database exec supabase start --runtime native in a supported sandbox without a container engine. The first start builds the database from apps/database/supabase/migrations/ and loads apps/database/supabase/seed.sql.
Connect both apps to the project
pnpm supabase:sync-envscripts/sync-supabase-env.ts runs supabase status --output-format json, reads the nested env object and writes the values into apps/web/.env and apps/admin/.env (creating a file from the example when one is missing, and leaving your other settings untouched):
CLI env key | App variable |
|---|---|
API_URL | SUPABASE_URL |
ANON_KEY | SUPABASE_ANON_KEY |
SERVICE_ROLE_KEY | SUPABASE_SERVICE_ROLE_KEY |
To see the same output yourself, including STUDIO_URL, MAILPIT_URL and MCP_URL:
pnpm --filter database exec supabase status --output-format jsonYou will need the Mailpit address for verification emails. If you use the repository's supabase-local MCP server with an AI coding tool, point its URL in .agents/config.json at MCP_URL and run pnpm agents:sync.
Regenerate database types (optional)
The generated types are committed at apps/database/lib/database.types.ts. Regenerate them after any schema change:
pnpm gen-types-localStart the dev servers
pnpm devThis runs every app's dev script in parallel through Turborepo: the web app on http://localhost:3000, the admin app on http://localhost:3002 (both from HOST and PORT in their .env files) and the React Email preview on http://localhost:3001. Use pnpm web#dev or pnpm admin#dev to start a single app.
Restart the dev servers after changing env values or switching branches.
Sign in and create a workspace
The seed creates four local accounts. Every one signs in with the password password123:
| Role | |
|---|---|
testadmin@usenextbase.com | Application admin, can open /admin on the admin app |
alice@example.com | Regular user |
bob@example.com | Regular user |
carol@example.com | Regular user |
These accounts exist only in local and CI databases. Never seed them into production.
To test the full flow instead, open http://localhost:3000/sign-up, create an account and confirm it from the local inbox. Local Supabase Auth requires email confirmation (enable_confirmations = true) and delivers mail to Mailpit ([local_smtp] in config.toml); open the MAILPIT_URL from the status output. The confirmation link returns to /auth/callback, then /app/onboarding asks you to accept the terms and create your first workspace. Add a project inside it so you have data for an agent later.
To try administration, sign in as testadmin@usenextbase.com at http://localhost:3002/login. The admin app has no sign-up page; it redirects / to /admin.
Verify the setup
pnpm check # format:check, lint, typecheck, unit tests and production builds of both apps
pnpm test-db # pgTAP tests; local Supabase must be running
pnpm test:e2e # Playwright smoke tests; starts the web and admin dev servers if neededpnpm check includes both app builds, each of which boots the built server and posts to a sign-in route as a smoke test (scripts/check-built-auth.mjs) before packaging a Vercel Build Output. The Playwright suite in apps/web/e2e/ signs in with the seeded admin account against the admin app (ADMIN_BASE_URL, default http://127.0.0.1:3002), so run it against a freshly seeded database.
Stop, reset and switch
pnpm db:stop
pnpm --filter database exec supabase db resetdb:stop keeps the project's data. db reset replays every migration and the seed file; run it after changing SQL, then pnpm test-db and pnpm gen-types-local. When you switch branches, start that worktree's project, run pnpm supabase:sync-env again so both .env files point at it, and restart pnpm dev. The troubleshooting page covers the common failures.