Nextbase Docs
Nextbase Docs
HomeBlogWelcome to Nextbase v5!Choose your starterGetting startedLocal Supabase per agent
Next.js + ConvexInstallationEnvironment variablesAuthenticationAgent connectionsProject structureDeployment
AuthenticationWorkspaces and the admin area
Building with agentsEmails with Resend
TroubleshootingNextbase v5
The 8 starter kitsNext.js + Convex

Next.js + Convex

Overview of the Next.js + Convex starter: what it ships, what you need, and where to go next.

This kit uses Next.js App Router, a Convex backend and Convex Auth. You get the account, workspace and project foundation, a separate admin application, and separate agent connections for users and application administrators.

Open the live demo · Repository

The stack

LayerWhat the kit uses
FrontendNext.js 16 App Router, React 19, Cache Components, Tailwind CSS 4, shadcn/ui
AdminA second Next.js application in apps/admin on its own origin, sharing the same Convex backend
Backend and databaseConvex: document database, reactive queries, mutations, HTTP actions, file storage, crons
AuthenticationConvex Auth (@convex-dev/auth) with password, magic link, and optional GitHub and Google
Agent connectionsTwo convex-mcp-gateway component instances served from the Convex backend
EmailsReact Email templates in apps/email; Resend for production auth emails
Hosting used by the demoWeb and admin apps on Vercel, backend on Convex. A netlify.toml is also included for the web app

Convex replaces the separate database, realtime and storage services you would otherwise run. Locally, the Convex CLI manages a local backend for you, so there is no Docker in this kit.

What you get out of the box

  • Sign-up, login, email verification, magic links and password reset through Convex Auth.
  • Onboarding that completes a profile and creates the first workspace.
  • Workspaces with owner, admin, member and readonly roles, invitations and member management.
  • Workspace-scoped projects with comments and reactive updates.
  • In-app notifications, feedback boards, a public roadmap, an MDX blog, a changelog and a Fumadocs documentation site.
  • A dedicated admin application (apps/admin, port 3002) serving /app-admin: users, workspaces, marketing content, feedback moderation, the payment gateway, admin agent connections and audited user impersonation. The demo admin runs at https://nextjs-convex-admin.usenextbase.com.
  • A platform:grantAdmin internal mutation to promote your first application administrator from the CLI.
  • A User MCP at /mcp/user and a read-only Admin MCP at /mcp/admin, both with OAuth consent.
  • Convex file storage with application-owned metadata.
  • 41 React Email templates with a preview server.
  • Stripe, PostHog, Sentry and OpenTelemetry integrations that you enable through environment variables.

Some paths still use Supabase code

The core login, onboarding, workspace and project paths use Convex Auth and Convex data. Some older advanced settings, billing and application routes still contain Supabase actions: at the time of writing, 36 files under apps/web/src and 21 under apps/admin/src still import from src/supabase-clients/, including payments/stripe-payment-gateway.ts. The billing tables exist in the Convex schema but have no Convex functions yet. Review and migrate those paths before relying on them in your product.

Prerequisites

RequirementDetail
Node.js24 (.nvmrc says v24; setup.sh refuses other majors)
pnpm11.1.2 through Corepack (packageManager in package.json)
DockerNot needed. Convex runs a local backend through its CLI
Convex accountOnly for cloud deployments. Local development uses the CLI-managed local backend
Resend accountFor production auth emails (AUTH_RESEND_KEY, AUTH_EMAIL_FROM on the Convex deployment)
Stripe, PostHog, SentryOptional, only for the integrations you enable

Next steps

  1. Installation: clone, install, run pnpm dev, create your first account, workspace and administrator.
  2. Environment variables: what lives in the web and admin env files and what lives on the Convex deployment.
  3. Authentication: providers, sessions, the admin app and how functions are protected.
  4. Agent connections: the User and Admin MCP servers, their tools and OAuth behaviour.
  5. Project structure: the monorepo and where to make changes.
  6. Deployment: publish the Convex backend and deploy the web and admin apps.

For concepts shared across all eight kits, start at getting started.

Deployment

Provision Supabase, apply the migrations and publish the TanStack + Supabase starter's web and admin apps to Vercel or any Node 24 host.

Installation

Clone the Next.js + Convex starter, start the local Convex backend with pnpm dev, and create your first account, workspace and administrator.

On this page

The stackWhat you get out of the boxPrerequisitesNext steps