Setup

Overview

This guide will walk you through installing and setting up ZeroStarter on your local machine. You'll learn how to clone the repository, install dependencies, configure environment variables, set up the database, and configure authentication.

Getting Started

Prerequisites

Setup

1. Scaffold your product. In a new, empty directory (its name becomes your project name), run:

   npx zerostarter@latest init

   This fetches the latest ZeroStarter, removes the sample content, rebrands it to your project, installs dependencies, and creates .env from .env.example with a generated BETTER_AUTH_SECRET. When Docker is running it also offers to provision a local Postgres (via pglaunch) and run migrations; pass --db to do that without prompting. A fresh fork starts on canary with main seeded from the initial commit (canary is one commit ahead).

   You only need git push origin canary. Pushing canary first makes it your default branch; on your next push a pre-push hook seeds main (the canary to main release flow needs main on the remote) and prints a link to enable read-write Actions permissions. See Release Management for the full flow.

2. Set up environment variables:

   init already creates .env from .env.example with a generated BETTER_AUTH_SECRET. Open it and fill in your remaining values (OAuth credentials, and POSTGRES_URL if you did not let init provision one). Only if you are converting an existing checkout in place, or .env is missing, create it manually first (this leaves BETTER_AUTH_SECRET empty, so generate one):

   cp .env.example .env

   The .env file contains the following variables:

   NODE_ENV=local
   
   # -------------------- Server variables --------------------
   
   HONO_APP_URL=http://localhost:4000
   HONO_TRUSTED_ORIGINS=http://localhost:3000
   HONO_RATE_LIMIT=60 # allow 60 req/min (default) and twice that for authenticated users
   HONO_RATE_LIMIT_WINDOW_MS=60000 # 1 minute (default)
   
   # Generate using `openssl rand -base64 32`
   BETTER_AUTH_SECRET=
   
   # Generate at `https://github.com/settings/developers`
   GITHUB_CLIENT_ID=
   GITHUB_CLIENT_SECRET=
   
   # Generate at `https://console.cloud.google.com/apis/credentials`
   GOOGLE_CLIENT_ID=
   GOOGLE_CLIENT_SECRET=
   
   # Generate using `bunx pglaunch -k`
   POSTGRES_URL=
   
   # -------------------- Client variables --------------------
   
   NEXT_PUBLIC_APP_URL=http://localhost:3000
   NEXT_PUBLIC_API_URL=http://localhost:4000
   
   # Optional: PostHog Analytics (https://zerostarter.dev/docs/manage/analytics)
   NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
   NEXT_PUBLIC_POSTHOG_KEY=
   
   # Optional: User feedback (https://zerostarter.dev/docs/manage/feedback)
   NEXT_PUBLIC_USERJOT_URL=

   Deployments (Docker, Vercel) may also set INTERNAL_API_URL (an optional server-only URL the Next.js app uses to reach the API directly, preferred over NEXT_PUBLIC_API_URL when present) and HONO_PORT (the port the Hono server listens on, default 4000).

Database Setup

1. Ensure your PostgreSQL server is running.

2. Run the generation:

   bun run db:generate

3. Run the migration:

   bun run db:migrate

Authentication Setup

ZeroStarter comes with some default authentication plugins using Better Auth, you can extend as needed.

GitHub

1. Create a GitHub OAuth App at GitHub Developer Settings.
2. Set the Homepage URL to http://localhost:3000.
3. Set the Authorization callback URL to http://localhost:4000/api/auth/callback/github.
4. Copy the Client ID and Client Secret into your .env file.

Google

1. Create a Google OAuth App in the Google Cloud Console.
2. Configure the OAuth consent screen (External).
3. Create an OAuth Client ID (Application type: Web).
4. Set the Authorized JavaScript origins to http://localhost:3000.
5. Set the Authorized redirect URI to http://localhost:4000/api/auth/callback/google.
6. Copy the Client ID and Client Secret into your .env file.

Running the Application

bun dev

Running the Application with Docker Compose

docker compose up

Accessing the Application

• Frontend: http://localhost:3000
• Backend: http://localhost:4000
• API Docs: http://localhost:4000/api/docs