Installation

This guide walks you through installing the Next.js 16 Starter Kit and configuring your development environment.

System Requirements

:::info While Node.js works fine, we recommend using Bun for faster installs and better monorepo support. :::

Step 1: Clone the Repository

# Clone the monorepo
git clone <your-repository-url>
cd nextjs16-starter-kit

Step 2: Install Dependencies

Using Bun (recommended):

bun install

Using npm:

npm install

Step 3: Environment Configuration

Create your environment file:

cp .env.example .env.local

Edit .env.local and configure the required variables:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/dbname"

# Authentication (choose your provider)
AUTH_PROVIDER="better-auth" # or "clerk", "next-auth"
AUTH_SECRET="your-secret-key"

# AWS (for email infrastructure)
AWS_REGION="us-east-1"
AWS_ACCESS_KEY_ID="your-access-key"
AWS_SECRET_ACCESS_KEY="your-secret-key"

# Stripe (for billing)
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

Step 4: Database Setup

Generate and run migrations:

# Generate Drizzle migrations
bun run db:generate

# Run migrations
bun run db:migrate

# (Optional) Seed the database
bun run db:seed

:::warning The db:push command is for development only and can overwrite data. Always use db:migrate for production. :::

Step 5: Start Development Server

# Start with Turbo TUI
bun run dev

Your application will be available at http://localhost:3000.

Verification

After starting the server, verify everything works:

1. Open http://localhost:3000 - You should see the homepage
2. Check http://localhost:3000/api/health - Should return status 200
3. Open Drizzle Studio: bun run db:studio

Common Issues

Port Already in Use

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

Database Connection Failed

• Verify PostgreSQL is running
• Check DATABASE_URL format
• Ensure database exists: createdb dbname

Missing Environment Variables

The app will warn about missing required variables on startup. Check the Environment Variables reference for the full list.

Next Steps

• Configure Authentication
• Set up Email Infrastructure
• Configure Billing