Getting Started

Get up and running fast. Auth is already configured — you just connect the services and set your environment variables.

The package manager is Bun. All commands use bun — do not substitute npm or pnpm.

What You're Setting Up

You're not configuring auth — that's already done. You're just:

Installing dependencies and starting Convex (auth runs inside Convex)
Setting the Next.js environment (.env.local)
Setting the Convex deployment environment
Generating the JWKS signing keys
Wiring up Autumn billing
Running the app

Prerequisites

You'll need accounts on the following services (all have free tiers):

Bun — the package manager and runtime.
Convex — real-time database + backend. Auth runs inside Convex.
Resend — transactional email (verification, OTP, invitations). You'll need an API key and a verified sender.
Autumn — organization-scoped subscription billing.
(Optional) Sentry — error monitoring. The app runs fine without it.

Installation

Clone the Repository

git clone https://github.com/unstack-pro/nextjs-convex.git  # Purchasing grants access to the private repo
cd nextjs-convex

Install and Start Convex

bun install
bun convex dev          # in a dedicated terminal — keep it running

The first bun convex dev run logs you into Convex, creates a deployment, and pushes the schema/functions. It also writes CONVEX_DEPLOYMENT and the Convex URLs into .env.local. Leave it running throughout development.

Configure the Next.js Environment (`.env.local`)

Copy the example file and fill in your values. See Environment Variables for the full reference.

cp .env.example .env.local

.env.local

# Printed by `bun convex dev` (….convex.cloud) — swap .cloud for .site for the site URL
NEXT_PUBLIC_CONVEX_URL="https://your-deployment.convex.cloud"
NEXT_PUBLIC_CONVEX_SITE_URL="https://your-deployment.convex.site"

NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_APP_NAME="Unstack Pro"

# Required in BOTH the Next.js env AND the Convex deployment (step 5)
AUTUMN_SECRET_KEY="am_sk_..."

Configure the Convex Deployment Environment

These live on the Convex deployment, not in .env.local. Set each with bunx convex env set NAME "value" (or via the Convex dashboard):

# Random secret — set this BEFORE generating JWKS (next step)
bunx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)"

# Email
bunx convex env set RESEND_API_KEY "re_..."
bunx convex env set EMAIL_FROM "Unstack Pro <noreply@yourdomain.com>"

# Billing (also required in .env.local)
bunx convex env set AUTUMN_SECRET_KEY "am_sk_..."

# Passkeys + app identity (same values as .env.local)
bunx convex env set PASSKEY_RP_ID "localhost"
bunx convex env set NEXT_PUBLIC_APP_URL "http://localhost:3000"
bunx convex env set NEXT_PUBLIC_APP_NAME "Unstack Pro"

EMAIL_FROM must be a Resend-verified sender — every email flow throws if it's missing.

Generate the JWKS Signing Keys

Better Auth signs the Convex JWTs with an RS256 key pair. convex/auth.config.ts reads the public key set from the JWKS env var, and Better Auth signs with the stored private key (encrypted with BETTER_AUTH_SECRET, so set that first).

With bun convex dev running (so the functions are deployed):

# Prints the JWKS document set
bunx convex run betterAuth/auth:getLatestJwks

Set the output as the JWKS env var. On macOS/Linux, one step:

bunx convex env set JWKS "$(bunx convex run betterAuth/auth:getLatestJwks)"

On Windows, copy the printed JSON array and paste it into bunx convex env set JWKS '…'.

To rotate keys later, run bunx convex run betterAuth/auth:rotateKeys and set the result as JWKS again — this logs out all users.

Configure Autumn Billing

Subscriptions are defined in autumn.config.ts (a free_plan and a seat-metered pro plan). Push them to your Autumn account and wire up the secret key:

bunx atmn login          # authenticate the Autumn CLI
bunx atmn push           # create the products from autumn.config.ts

Then set AUTUMN_SECRET_KEY in both .env.local and on the Convex deployment (steps 3 and 4) using the key from the Autumn dashboard.

Run the App

bun dev                  # Next.js dev server (Turbopack)

Open http://localhost:3000. Keep bun convex dev running in its own terminal. 🎉

Commands

bun dev                  # Next dev server (turbopack)
bun convex dev           # Convex backend — required for the app to function
bun run build            # tsgo --noEmit && next build --turbopack
bun run lint             # biome lint .
bun run format           # biome format --write .

Verify Installation

Visit the homepage: navigate to http://localhost:3000
Register an account: create a test account and complete email verification
Check the Convex dashboard: confirm data is being created
Explore features: log in, create an organization, invite a member

Next Steps

📖 Authentication — understand the auth system
🏢 Organizations — multi-tenant features
🔧 Environment Variables — complete configuration
🏗️ Project Structure — understand the codebase
🔄 Template Updates — pull ongoing template fixes
🚀 Deployment — get ready for production

Common Issues

Convex Connection Issues

Make sure your Convex dev server is running:

bun convex dev

Environment Variable Not Found

Double-check that:

.env.local exists in the root directory
Convex-side variables are set via bunx convex env set (or the dashboard)
If Convex throws that a variable is missing, consult createAuthOptions in convex/betterAuth/auth.ts

Authentication Errors

Ensure:

BETTER_AUTH_SECRET and JWKS are set on the Convex deployment
NEXT_PUBLIC_APP_URL matches your dev URL
bun convex dev is running

Never commit your .env.local file to version control. It contains sensitive secrets.

Getting Started

On this page