Skip to Content
Local Setup

Local Setup

The local setup order matters more than most people expect.

Use this order:

  1. Clerk
  2. Convex
  3. Stripe

If you skip the order, the app can look close to working while the paid-access handoff is still broken.

Before you start

Have these ready:

  • Node.js LTS
  • bun
  • a Clerk account
  • a Convex account 
  • a Stripe account
  • a Vercel account for deployment later
  • a GitHub account if you plan to use the Build starter-template path later

First local boot

Install the repo and copy the local env template:

bun install
cp apps/web/.env.local.example apps/web/.env.local

Then connect the repo to your hosted Convex dev deployment:

bun run dev:convex

That command runs convex dev and writes NEXT_PUBLIC_CONVEX_URL, NEXT_PUBLIC_CONVEX_SITE_URL, and CONVEX_DEPLOYMENT into apps/web/.env.local for your per-developer hosted Convex dev deployment.

Then follow the provider wiring pages in this order:

Once those values are in place, start the local app:

bun run dev

If you are actively testing checkout or the purchase-to-access handoff, run the full local environment instead:

bun run dev:full

Open http://localhost:3000.

Which local command to use

Use these commands intentionally:

bun run dev
bun run dev:full
bun run dev:web
bun run dev:convex
bun run dev:stripe
  • bun run dev starts the app locally and keeps your hosted Convex dev deployment synced
  • bun run dev:full starts the app, hosted Convex dev sync, and Stripe webhook forwarding together
  • bun run dev:web starts only the Next.js side
  • bun run dev:convex connects or refreshes your hosted Convex dev deployment and keeps the backend synced
  • bun run dev:stripe waits for hosted Convex dev env values, checks the pinned Stripe CLI project ship-by-sunday, warns with stripe login --project-name ship-by-sunday if the local CLI context drifted, then starts the Stripe listener from the app STRIPE_SECRET_KEY

This repo does not support Convex’s local backend mode as a separate development mode.

The fastest way to confirm the setup

Once the app boots, validate the basics:

bun run build
bun run stripe:dev:doctor

bun run stripe:dev:doctor compares the app Stripe account in apps/web/.env.local against the pinned Stripe CLI project ship-by-sunday. If that profile is missing or points at the wrong account, repair it with:

stripe login --project-name ship-by-sunday

Then finish the real flow with Local QA.

What success looks like

You are ready for real customization when:

  • the marketing page loads locally
  • /docs loads locally
  • you can reach sign-in
  • Convex connects cleanly to your hosted dev deployment
  • Stripe listener setup does not report account or secret drift
  • the app can complete the local QA flow without fake shortcuts

If this breaks

Last updated on
How the Starter WorksClerk + Convex Auth