Clone the Repository

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

Install Dependencies

npm install

pnpm install

yarn install

bun install

Set Up Convex

1. Create a Convex account at convex.dev

2. Install Convex CLI (if not already installed):

   npm install -g convex

3. Initialize Convex in your project:

   npx convex dev

   This will:

   • Create a new Convex deployment
   • Generate your deployment URL
   • Start the Convex dev server

4. Note your Convex URLs - you'll need these for environment variables:

   • CONVEX_DEPLOYMENT
   • NEXT_PUBLIC_CONVEX_URL
   • NEXT_PUBLIC_CONVEX_SITE_URL

Configure Environment Variables

1. Copy the example environment file:

   cp .env.example .env.local

2. Fill in your environment variables. See the Environment Variables page for detailed explanations.

   Minimum required variables (all are required for the app to function):

   BETTER_AUTH_SECRET="your-generated-secret"
   BETTER_AUTH_URL="http://localhost:3000"
   RESEND_API_KEY="re_your_resend_api_key"
   EMAIL_FROM="Your App <no-reply@yourdomain.com>"
   AUTUMN_API_KEY="am_sk_your_autumn_key"
   NEXT_PUBLIC_APP_URL="http://localhost:3000"
   CONVEX_DEPLOYMENT="dev:your-deployment-name"
   NEXT_PUBLIC_CONVEX_URL="https://your-deployment.convex.cloud"
   NEXT_PUBLIC_CONVEX_SITE_URL="https://your-deployment.convex.site"
   PASSKEY_RP_ID="localhost"
   NEXT_PUBLIC_APP_NAME="Your App Name"

3. Set up Convex environment variables:

   # Authentication
   npx convex env set BETTER_AUTH_SECRET "your-generated-secret"
   npx convex env set BETTER_AUTH_URL "http://localhost:3000"
   
   # Email
   npx convex env set RESEND_API_KEY "re_your_resend_api_key"
   npx convex env set EMAIL_FROM "Your App <no-reply@yourdomain.com>"
   
   # Payments (optional - only if using billing)
   npx convex env set AUTUMN_API_KEY "am_sk_your_autumn_key"
   
   # Application
   npx convex env set NEXT_PUBLIC_APP_URL "http://localhost:3000"
   npx convex env set NEXT_PUBLIC_APP_NAME "Your App Name"
   
   # Passkeys
   npx convex env set PASSKEY_RP_ID "localhost"

Generate Authentication Secret

Generate a secure random secret for Better Auth:

openssl rand -base64 32

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Use this value for BETTER_AUTH_SECRET in both .env.local and Convex environment.

Set Up Email (Required)

Email verification is required for users to sign in. You'll need a Resend account:

1. Sign up at resend.com
2. Get your API key
3. Add to .env.local and Convex:

   RESEND_API_KEY="RESEND API KEY"
   EMAIL_FROM="Unstack Pro <no-reply@auth.unstack.pro>"

Start Development Server

npm run dev

pnpm dev

yarn dev

bun dev

Your app should now be running at http://localhost:3000! 🎉