Installation

Get your development environment up and running in just a few minutes.

Prerequisites

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

Node.js 20.x or higher (Download)
pnpm 10.x or higher (recommended) or npm/yarn
PostgreSQL database (Neon, Supabase, or local)
Git for version control

Installing pnpm

If you don't have pnpm installed:

npm install -g pnpm

Or using Homebrew on macOS:

brew install pnpm

Step 1: Install Dependencies

Navigate to the project directory and install all dependencies:

pnpm install

This will install all the required packages including:

Next.js and React
Database tools (Drizzle ORM)
UI components (shadcn/ui, Radix UI)
Authentication (Better Auth)
And many more dependencies

Note: Why pnpm? This project uses pnpm for faster installs and better disk space efficiency. You can use npm or yarn, but pnpm is recommended.

Step 2: Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Now open .env and configure the following required variables:

Database Configuration

DATABASE_URL="postgresql://user:password@host:5432/database?sslmode=require"

Create account at Neon 2. Create a new project 3. Copy the connection string from the dashboard 4. Paste it into DATABASE_URL

Create account at Supabase 2. Create a new project 3. Go to Project Settings > Database 4. Copy the "Connection string" (URI format) 5. Paste it into DATABASE_URL

DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/yourdbname"
``` Make sure PostgreSQL is running on your machine.



### Authentication Configuration

Generate a secure secret for Better Auth:

```bash
openssl rand -base64 32

Then set it in your .env:

BETTER_AUTH_SECRET="your-generated-secret"
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Admin Setup

Set the email address for your first admin user:

FIRST_ADMIN_EMAIL="your-email@example.com"

You'll sign up with this email and then run a script to promote yourself to admin.

Optional Configurations

The following are optional but recommended for full functionality:

OAuth Providers (Optional)

Google OAuth

Go to Google Cloud Console 2. Create a new project or select existing 3. Enable Google+ API 4. Configure OAuth consent screen 5. Create OAuth 2.0 credentials 6. Add authorized redirect URI: http://localhost:3000/api/auth/callback/google 7. Copy Client ID and Client Secret to .env: bash GOOGLE_CLIENT_ID="your-google-client-id" GOOGLE_CLIENT_SECRET="your-google-client-secret"

GitHub OAuth

Go to GitHub Settings > Developer settings > OAuth Apps 2. Click "New OAuth App" 3. Set Homepage URL: http://localhost:3000 4. Set Authorization callback URL: http://localhost:3000/api/auth/callback/github 5. Copy Client ID and Client Secret to .env: bash GITHUB_CLIENT_ID="your-github-client-id" GITHUB_CLIENT_SECRET="your-github-client-secret"

Email Configuration (Optional but Recommended)

For password reset and email verification, configure an email provider:

# Choose a provider: "nodemailer" | "resend" | "sendgrid" | "mailgun"
EMAIL_PROVIDER="nodemailer"

# For Gmail SMTP (default nodemailer)
EMAIL_HOST="smtp.gmail.com"
EMAIL_PORT="587"
EMAIL_USER="your-email@gmail.com"
EMAIL_PASS="your-app-password"
EMAIL_FROM="Your App <noreply@yourapp.com>"

See the Email Configuration guide for detailed setup for each provider.

Stripe Configuration (Optional)

For subscription payments:

STRIPE_SECRET_KEY="sk_test_..."
STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

See the Stripe Setup guide for detailed configuration.

UploadThing (Optional)

For file uploads:

UPLOADTHING_TOKEN="your-uploadthing-token"

Get your token from UploadThing Dashboard.

AI Writing Assistant (Optional)

For AI-powered blog writing:

OPENROUTER_API_KEY="your-openrouter-api-key"

Get your API key from OpenRouter. The starter kit uses FREE models by default!

Step 3: Database Setup

Push the database schema to your database:

pnpm db:push

This creates all the necessary tables in your PostgreSQL database.

Note: First time setup? Use pnpm db:push to apply the schema. For future changes, you may want to use migrations.

Step 4: Automated Setup (Recommended)

Run the automated setup script to seed initial data:

pnpm project:setup

This will:

✅ Validate your environment variables
✅ Push database schema (if not already done)
✅ Create subscription plans
✅ Seed blog categories and tags
✅ Create a welcome blog post
✅ Set up initial data

Note: Tip: This is the fastest way to get started! It handles all the initial setup in one command.

Manual Setup (Alternative)

If you prefer to set things up manually:

# Push database schema
pnpm db:push

# Seed subscription plans
pnpm plans:setup

# Seed blog data
pnpm blog:seed

# Optional: Seed testimonials
pnpm testimonials:seed

# Optional: Seed email templates
pnpm email:seed

Step 5: Start Development Server

Start the Next.js development server:

pnpm dev

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

Note: Turbopack: The dev command uses Turbopack for faster builds. This is a Next.js 16 feature!

Step 6: Create Your First Admin User

Sign up at http://localhost:3000/sign-up using the email you set in FIRST_ADMIN_EMAIL
Verify your email (if email is configured) or check the console logs for the verification link
Promote to admin by running:

pnpm admin:setup

Sign in again to access admin features
Navigate to http://localhost:3000/dashboard/admin to see your admin dashboard

Note: Success! You now have full admin access to manage users, content, and settings.

Verification

To verify everything is working correctly:

✅ Visit the homepage at http://localhost:3000
✅ Sign up with a new account
✅ Sign in with your admin account
✅ Access the admin dashboard at /dashboard/admin
✅ Check the blog at /blog
✅ Try creating a new blog post

Next Steps

Now that you're set up, explore the features:

Installation

On this page