Quickstart

This guide gets you from zero to a running dev server with the minimum required setup. Only two services are truly required to boot: Clerk (authentication) and a PostgreSQL database.

Don't worry about other environment variables — features that need them (Stripe, analytics, email, etc.) will gracefully degrade or show warnings. You can add them later.

Prerequisites

You need Node.js 18+ and a package manager. We recommend Bun, but npm, yarn, and pnpm all work.

Terminal

node -v # Should be v18 or higher

Initialize the project

npx next-forge@latest init

You'll be prompted for a project name and package manager. Once complete, cd into your new project directory.

Set up Clerk

Sign up at clerk.com and create a new application
Go to API Keys in your Clerk dashboard
Copy the Publishable key (pk_test_...) and Secret key (sk_test_...)

Add them to both apps/app/.env.local and apps/web/.env.local:

CLERK_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/"

The NEXT_PUBLIC_CLERK_*_URL values are already set in the .env.example files. You only need to add the two API keys.

Set up the database

Get a free PostgreSQL database from Neon (or use any Postgres instance), then add the connection string to packages/database/.env:

DATABASE_URL="postgresql://user:password@host:5432/dbname"

Then run the migration to scaffold your tables:

npm run migrate

Start the dev server

npm run dev

Your apps are now running at:

http://localhost:3000 — Main app
http://localhost:3001 — Marketing website
http://localhost:3002 — API
http://localhost:3003 — Email preview
http://localhost:3004 — Docs

Next steps

Now that you're up and running, you can:

Review the full environment variables page to enable optional features
Set up Stripe for payments
Set up Resend for transactional emails
Set up BaseHub for CMS content
Configure analytics, error tracking, and logging
Read the deployment guide when you're ready to go live