Nextbase Docs
Nextbase Docs
HomeBlogWelcome to Nextbase v5!Choose your starterGetting startedLocal Supabase per agent
TanStack + NeonInstallationEnvironment variablesAuthenticationAgent connectionsProject structureDeployment
AuthenticationWorkspaces and the admin area
Building with agentsEmails with Resend
TroubleshootingNextbase v5
The 8 starter kitsTanStack + Neon

TanStack + Neon

What the TanStack + Neon starter ships, what you need to run it, and where to go next.

This kit uses React Router framework mode, Express and TanStack Query, with Neon Postgres, Drizzle and Better Auth. You get the account, workspace and project foundation, a separately deployed admin application, and OAuth-protected MCP servers for users and application administrators.

Open the live demo · Admin demo · Repository

The repository name still says PlanetScale

The GitHub repository is called tanstack-planetscale-starter and the local Compose project is named nextbase-planetscale. Both names are historical. There is no TanStack Router and no PlanetScale code in the kit: the router is React Router and the production database is Neon Postgres. You don't need a PlanetScale account.

The stack

LayerWhat the kit uses
FrontendReact Router 8 framework mode with server-side rendering, React 19, TanStack Query, Tailwind CSS 4
ServerExpress 5 hosting the React Router build, Better Auth, a /api/v1 HTTP API and the MCP routes. One server per app: apps/web for the product, apps/admin for administration
DatabaseNeon Postgres in production; PostgreSQL 18 plus PgBouncer in Docker locally. Drizzle schema with reviewed SQL migrations, forced row-level security and least-privilege runtime roles
AuthenticationBetter Auth with database sessions, email and password, optional Google, GitHub and X providers, and the admin plugin with user, support and admin roles
EmailNodemailer over SMTP from a transactional outbox (app.outbox_jobs). A worker process sends locally; Vercel uses waitUntil plus a cron. Mailpit catches local mail. React Email templates live in apps/email
AgentsUser MCP on the web origin and Admin MCP on the admin origin, both OAuth with PKCE and read-only tools
Hosting used by the demoTwo Vercel projects (web and admin) and one Neon project

What you get out of the box

  • Accounts: sign-up with required email verification, sign-in, password reset. Social providers appear when their keys are set. The magic link plugin is configured on the server; the shipped login page is password only.
  • Workspaces: creation from the app or through POST /api/v1/workspaces, membership roles owner, admin, member and readonly, and a dashboard that lists the workspaces you belong to.
  • A seeded Acme Inc. workspace with a Launch project, plus the schema for projects, comments, invitations, notifications, media, feedback, roadmap, blog, billing and API keys. Only the account and workspace flows have UI in this kit; the other tables are ready for your features.
  • A separate admin application (apps/admin, port 3001) with a users list and audited impersonation: an administrator enters a support reason, the kit creates a 15-minute impersonated session, and the web app shows a banner with a way back to admin.
  • User MCP and Admin MCP with OAuth, so an agent can read account context and projects, or list users and workspaces. See agent connections.
  • An outbox worker with leases, heartbeats, exponential backoff and dead-lettering after 10 attempts.
  • Structured pino logs, request IDs, a CSP nonce per request, /healthz and /readyz probes on both apps.
  • Agent instruction files for Claude Code, Codex, Cursor, Gemini CLI, Copilot and others, generated from AGENTS.md by pnpm agents:sync.

Every protected operation is authorized in a domain service and constrained again by PostgreSQL RLS. The kit uses four login roles: migration_owner, app_runtime, auth_runtime and worker_runtime. None of the runtime roles can bypass RLS. A fifth role, function_owner, has no login and owns the reviewed SECURITY DEFINER helpers.

Prerequisites

RequirementVersion or account
Node.js24 (.nvmrc says 24, engines.node is >=24)
pnpm11.1.2, pinned by the packageManager field. Run corepack enable and let it pick the version
Docker with ComposeNeeded locally for PostgreSQL, PgBouncer, Mailpit and MinIO
Neon accountFor the production database
Vercel accountFor the web and admin deployments. The demo uses two Vercel projects
Email providerAny SMTP provider for production mail. The demo uses Resend's SMTP endpoint
OptionalGoogle, GitHub and X developer accounts for social sign-in

Next steps

  1. Installation: clone, start Docker, migrate, seed and run the web and admin servers.
  2. Environment variables: every variable in .env.example and apps/admin/.env.example.
  3. Authentication: Better Auth, roles, the admin app and the RLS boundary.
  4. Agent connections: User MCP, Admin MCP and the tools they expose.
  5. Project structure: the monorepo and where to make changes.
  6. Deployment: Neon roles, migrations, two Vercel projects and smoke checks.

If you are new to Nextbase v5, read getting started first for the shared flow.

Deployment

Put the Next.js + Neon starter in production: a Neon database, migrations, two Vercel projects for the web and admin apps, and post-deploy checks.

Installation

Run the TanStack + Neon starter locally with Docker, apply migrations and seed data, start the web and admin apps, and create your first account.

On this page

The stackWhat you get out of the boxPrerequisitesNext steps