Installation
Clone the Next.js + Supabase starter, start a local Supabase project, run the web and admin apps and sign in for the first time.
This page gets the kit running on your computer. It follows the local Supabase per agent flow, so each git worktree gets its own Supabase project with ports assigned by the CLI. Read that page once before you start; this page only repeats the commands you need.
The repository already uses the stack engine
apps/database/package.json pins the Supabase CLI to 2.121.0 and apps/database/supabase/config.toml sets [experimental] stack = true with no fixed ports. The kit's own scripts (setup.sh, pnpm database#start, pnpm supabase:sync-env, apps/web/scripts/generate-env-local.ts and the Playwright global setup) all read the project's URLs from supabase status --output-format json, so you do not need to edit the config or work around the scripts.
Clone the repository
git clone https://github.com/usenextbase/nextjs-supabase-starter.git
cd nextjs-supabase-starterIf GitHub says the repository doesn't exist, sign in with the account that has access.
Use Node.js 24 and pnpm 11
nvm use
corepack enable
pnpm install.nvmrc pins v24. Corepack reads packageManager: pnpm@11.1.2 from the root package.json. pnpm install also runs fumadocs-mdx in apps/web as a postinstall step.
Create the env files
Only when they are missing:
[ -f apps/web/.env.local ] || cp apps/web/.env.local.example apps/web/.env.local
[ -f apps/admin/.env.local ] || cp apps/admin/.env.local.example apps/admin/.env.localNever overwrite an existing .env.local. The web example sets NEXT_PUBLIC_SITE_URL=http://localhost:3000 and USE_LOCAL_EMAIL=true; the admin example sets NEXT_PUBLIC_SITE_URL=http://localhost:3002 and NEXT_PUBLIC_WEB_APP_URL=http://localhost:3000. Both carry placeholder Supabase values that the next steps replace. See environment variables.
Start the local Supabase project
pnpm database#startThis runs supabase start in apps/database. Use pnpm --filter database exec supabase start --runtime native in a supported sandbox without Docker. Starting applies every migration in apps/database/supabase/migrations/ and runs apps/database/supabase/seed.sql.
Then write the project's URL and keys into both apps:
pnpm supabase:sync-envscripts/sync-supabase-env.ts runs supabase status --output-format json and rewrites NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY and SUPABASE_SECRET_KEY in apps/web/.env.local and apps/admin/.env.local, leaving every other line alone. To look at the values yourself:
pnpm --filter database exec supabase status --output-format jsonThe JSON env object also contains STUDIO_URL, DB_URL and MAILPIT_URL. Copy MAILPIT_URL into apps/web/.env.local as MAILPIT_URL so the web app's local emails reach this project's Mailpit (the example has the line commented out).
setup.sh at the repository root performs this step and the previous two for you: copy missing env files, pnpm i, start Supabase, pnpm supabase:sync-env, pnpm gen-types-local.
Generate database types
pnpm gen-types-localThis writes apps/database/lib/database.types.ts, which apps/web and apps/admin import as database/types. Run it again after you add a migration.
Start the dev servers
pnpm devpnpm dev runs turbo run dev --parallel, which starts the Next.js web app on http://localhost:3000, the React Email preview on http://localhost:3001 and the admin app on http://localhost:3002. Use pnpm web#dev for the web app alone and pnpm admin#dev for the admin app alone.
Restart the dev servers after you refresh connection details or switch branches.
Sign up and create a workspace
Open http://localhost:3000/sign-up. Local Supabase Auth has enable_confirmations = true, so the app waits until you open the verification link. Find it in Mailpit at the MAILPIT_URL from supabase status.
After verifying, onboarding asks for your profile and creates your first workspace. Add a project from the workspace page so you have data to test with later.
The seed also creates four test users, including the application admin testadmin@usenextbase.com. Their shared password is written at the top of the users section in apps/database/supabase/seed.sql.
Sign in to the admin app
Open http://localhost:3002/login and sign in with the seeded admin account (email and password). The admin app redirects / to /app-admin and returns 403 for accounts without the admin role. See authentication for how to grant the role to your own account.
Verify the setup
pnpm verify:localThis copies any missing .env.local files, then runs lint, typecheck and Vitest unit tests across the workspace (web and admin included) and a compile-mode production build of the web app. It does not need the Supabase stack. The build step calls apps/web/scripts/generate-env-local.ts, which skips env generation when the three Supabase variables are already set and otherwise reads them from supabase status --output-format json.
For database tests and browser tests, with Supabase running:
pnpm --filter database test-db
pnpm test-integrationtest-db runs the pgTap suites in apps/database/supabase/tests/. test-integration runs Playwright from apps/web. Its global setup reads supabase status --output-format json and writes the Supabase URL, keys, DB_URL and MAILPIT_URL into apps/web/.env.test.local. The config starts the web app with pnpm start on the port in PORT (default 3000) and the admin app with pnpm --filter admin start on 3002 unless ADMIN_BASE_URL points at a running instance; the e2e/admin/ specs run against the admin origin.
Local email
Two different senders exist locally:
- Supabase Auth sends verification, magic link and recovery emails through the local mail server. Open them at
MAILPIT_URL. - The web app's own emails (invitations, notifications) go through
apps/web/src/utils/api-routes/utils.ts. WithUSE_LOCAL_EMAIL=truethey are posted to the Mailpit API atMAILPIT_URL(apps/web/src/utils/send-email-mailpit.ts), falling back tohttp://localhost:54324when the variable is unset. The admin app's copy ofsend-email-mailpit.tsstill posts tohttp://localhost:54324; edit that URL if your project's Mailpit runs on a different port and you want admin emails locally.
Stop or reset
pnpm database#stopStopping keeps the project's data. To rebuild the database from migrations and seed:
pnpm --filter database exec supabase db reset --localSee stop or switch projects before using supabase stack destroy. If something fails, check troubleshooting.