Local Setup

Docs are in beta — content is improving rapidly. Found something missing? Open an issue on GitHub or reach out on Twitter (X).

What Works In This Quick Start

After completing this page, you will have BetterStarter working locally:

Local app running at http://localhost:3000
Drizzle migrations applied to your local PostgreSQL database
Auth working with local database
Blog and Docs enabled

This quick start does not fully configure third-party integrations like Stripe, PostHog, Plunk email, or social OAuth providers.

Local Email Behavior

For the fastest local setup, you do not need Plunk.

In development without Plunk, BetterStarter logs OTP codes, magic links, reset-password links, and other auth email values to the server console
If you do configure Plunk locally, BetterStarter will send real emails
In production, you need Plunk or another real email provider because users must receive actual emails

Step 0 - Prerequisites

Node.js 22+
pnpm
PostgreSQL running locally

Step 1 - Clone And Install

git clone https://github.com/azizali/betterstarter.git
cd betterstarter
pnpm install
cp .env.sample .env.local

Step 2 - Create a Local PostgreSQL Database

Pick one option.

Option A: Postgres.app (macOS)

Install Postgres.app - macOS only

createdb betterstarter

Option B: Docker

docker run --name betterstarter-db \
	-e POSTGRES_DB=betterstarter \
	-e POSTGRES_USER=postgres \
	-e POSTGRES_PASSWORD=postgres \
	-p 5432:5432 \
	-d postgres:16

Step 3 - Set Required `.env.local` Values

Open .env.local and set:

APP_BASE_URL=http://localhost:3000
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=<generate with: npx @better-auth/cli secret>
DATABASE_URL=postgres://postgres:postgres@localhost:5432/betterstarter

If you are not using Docker, update DATABASE_URL for your local Postgres user/password.

Step 4 - Run Migrations

pnpm db:migrate

Step 5 - Start The App

pnpm dev

Open http://localhost:3000.

Enable and configure additional features

BetterStarter has additional features that can be enabled from src/appConfig.ts

Follow the guide to enable each feature

Next Step

Go Live

On this page