Getting Started

Get up and running in 10 minutes. Auth is already configured—you just need to connect the services.

No auth setup required. Just connect Convex, Resend, and Autumn, then start building.

What You're Setting Up

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

Connecting to Convex (database)
Connecting to Resend (emails - required for sign-in)
Connecting to Autumn (billing - required for organizations)
Setting a secret key

That's it. Then you have a fully working app with auth, organizations, and admin.

Prerequisites

Before you begin, make sure you have the following installed:

Node.js 18+: Download here
npm, pnpm, yarn, or bun: Package manager of your choice
Git: Download here

Unstack Pro requires Node.js 18 or higher due to native crypto features used in authentication.

Installation

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

Create a Convex account at convex.dev
Install Convex CLI (if not already installed):
```
npm install -g convex
```
Initialize Convex in your project:
```
npx convex dev
```
This will:
- Create a new Convex deployment
- Generate your deployment URL
- Start the Convex dev server
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

Copy the example environment file:
```
cp .env.example .env.local
```

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

Minimum required variables:

BETTER_AUTH_SECRET="your-secret-key-generate-with-openssl"
BETTER_AUTH_URL="http://localhost:3000"
CONVEX_DEPLOYMENT="your-convex-deployment"
NEXT_PUBLIC_CONVEX_URL="https://your-project.convex.cloud"

Set up Convex environment variables:

npx convex env set BETTER_AUTH_SECRET "your-secret-key"
npx convex env set BETTER_AUTH_URL "http://localhost:3000"
npx convex env set RESEND_API_KEY "your-resend-key"
npx convex env set EMAIL_FROM "Your App <no-reply@example.com>"
npx convex env set AUTUMN_API_KEY "your-autumn-key"

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:

Sign up at resend.com
Get your API key

Add to .env.local and Convex:

RESEND_API_KEY="re_..."
EMAIL_FROM="Your App <no-reply@yourdomain.com>"

Email verification is required for sign-in. Without Resend configured, users cannot complete registration.

Start Development Server

npm run dev

pnpm dev

yarn dev

bun dev

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

Verify Installation

After starting the development server, you should:

Visit the homepage: Navigate to http://localhost:3000
Register an account: Click "Register" and create a test account
Check Convex dashboard: Log into your Convex dashboard to see data being created
Explore features: Try logging in, creating an organization, etc.

Next Steps

Now that you have Unstack Pro running locally, here are some recommended next steps:

📖 Learn about Authentication - Understand the auth system
🏢 Explore Organizations - Multi-tenant features
🔧 Review Environment Variables - Complete configuration
🏗️ Study Project Structure - Understand the codebase
🚀 Plan Deployment - Get ready for production

Common Issues

Convex Connection Issues

Make sure your Convex dev server is running:

npx convex dev

Environment Variable Not Found

Double-check that:

.env.local exists in the root directory
All required variables are set
Convex environment variables are configured via npx convex env set or their dashboard

Authentication Errors

Ensure:

BETTER_AUTH_SECRET is set in both .env.local and Convex
BETTER_AUTH_URL matches your development URL
Convex deployment is running

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

Development Tips

Hot Reload: Changes to your code will automatically reload
Convex Dashboard: Monitor your database in real-time at dashboard.convex.dev
Better Auth: Uses secure httpOnly cookies for session management
Type Safety: Full TypeScript support throughout the project

Need help? Check out the other documentation pages or review the code examples in the project.

Getting Started

On this page