Installation

This guide covers the complete setup process for ZeroStarter, including all prerequisites, environment configuration, database setup, and optional integrations like OAuth providers and analytics.

Prerequisites

Before installing ZeroStarter, ensure you have the following installed on your system:

Required

Bun Runtime

ZeroStarter requires Bun v1.3.7 or higher.Install Bun:

curl -fsSL https://bun.sh/install | bash

Verify installation:

bun --version
# Should output: 1.3.7 or higher

PostgreSQL Database

You need a PostgreSQL database (version 12 or higher).Option 1: Local PostgreSQL

# macOS
brew install postgresql@16
brew services start postgresql@16

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

Option 2: Managed Database

Neon (recommended for development)
Supabase
Railway
Vercel Postgres

Use bunx pglaunch -k to quickly generate a free PostgreSQL URL from supported providers.

Git

Required for version control.

git --version

Optional

Node.js: While not required (Bun is used), some tools may expect it
Docker: For containerized deployment
pnpm/npm: Only if you prefer these over Bun (not recommended)

Installation Steps

1. Clone the Repository

Clone ZeroStarter using gitpick for a clean copy without git history:

bunx gitpick https://github.com/nrjdalal/zerostarter/tree/main
cd zerostarter

Alternatively, you can fork the repository on GitHub and clone your fork:

git clone https://github.com/YOUR_USERNAME/zerostarter.git
cd zerostarter

2. Install Dependencies

Install all workspace dependencies:

bun install

This installs dependencies for:

api/hono - Backend API server
web/next - Frontend application
packages/auth - Shared authentication
packages/db - Database and ORM
packages/env - Environment variables
packages/tsconfig - TypeScript configuration

The postinstall script automatically runs dependency management tasks. This is configured in package.json:31.

3. Environment Configuration

Copy the example environment file:

cp .env.example .env

Now configure your .env file:

Essential Variables

# Environment (local, development, staging, production)
NODE_ENV=local

# API Server Configuration
HONO_APP_URL=http://localhost:4000
HONO_TRUSTED_ORIGINS=http://localhost:3000

# Rate Limiting (requests per minute)
HONO_RATE_LIMIT=60
HONO_RATE_LIMIT_WINDOW_MS=60000

Never commit your .env file to version control! The .gitignore is configured to exclude it, but always double-check.

OAuth Providers (Optional)

Configure social authentication providers:

GitHub OAuth

Go to GitHub Developer Settings
Click “New OAuth App”
Fill in the details:
- Application name: ZeroStarter Local
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3000/api/auth/callback/github
Click “Register application”
Generate a client secret
Add to .env:

GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

Google OAuth

Go to Google Cloud Console
Create a new project or select an existing one
Navigate to “Credentials” > “Create Credentials” > “OAuth client ID”
Configure the OAuth consent screen if prompted
Select “Web application” as the application type
Add authorized redirect URIs:
- http://localhost:3000/api/auth/callback/google
Click “Create”
Add to .env:

GOOGLE_CLIENT_ID="your-google-client-id.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

Analytics (Optional)

PostHog Analytics

PostHog provides product analytics, feature flags, and session recordings.

Sign up at PostHog
Create a new project
Get your project API key
Add to .env:

NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
NEXT_PUBLIC_POSTHOG_KEY="phc_your-project-key"

See the Analytics documentation for more details.

4. Database Setup

Generate and apply database migrations:

Generate Migrations

Generate Drizzle ORM migrations from your schema:

bun run db:generate

This reads your schema from packages/db/src/schema/ and creates migration files in packages/db/drizzle/.

Run Migrations

Apply migrations to your database:

bun run db:migrate

This creates all necessary tables for:

User accounts
Sessions
OAuth accounts
Email verification

Verify Database

Open Drizzle Studio to explore your database:

bun run db:studio

This opens a web interface at https://local.drizzle.studio where you can:

View all tables and data
Run queries
Modify records

The database schema is defined in packages/db/src/schema/auth.ts and uses Better Auth’s schema conventions.

5. Start Development

Start all development servers:

bun dev

This command:

Builds shared packages (@packages/env, @packages/db, @packages/auth)
Starts the Hono API server at http://localhost:4000
Starts the Next.js frontend at http://localhost:3000
Enables hot module reloading for all packages

You should see Turborepo’s TUI showing logs from all services:

• Packages in scope: @api/hono, @web/next, @packages/auth, @packages/db, @packages/env
• Running dev in 5 packages
• Remote caching disabled

@api/hono:dev: Server running at http://localhost:4000
@web/next:dev: ▲ Next.js 16.1.6
@web/next:dev: - Local:   http://localhost:3000

Verification

Verify your installation is working correctly:

API Health Check

Test the API server:

curl http://localhost:4000/api/health

Expected response:

{
  "data": {
    "message": "ok",
    "version": "0.0.14",
    "environment": "local"
  }
}

Frontend

Open http://localhost:3000 in your browser. You should see the ZeroStarter landing page.

API Documentation

Visit http://localhost:4000/api/docs to explore the interactive API documentation powered by Scalar.

Type-Safe API Client

Test the Hono RPC client by creating a test file:

web/next/test-api.ts

import { apiClient } from "@/lib/api/client"

const response = await apiClient.health.$get()
const { data } = await response.json()

console.log(data) // Fully typed!

Run it:

bun web/next/test-api.ts

Build for Production

Build all packages and applications:

bun run build

This creates optimized production builds:

api/hono/dist/ - Bundled API server
web/next/.next/ - Next.js production build
packages/*/dist/ - Built shared packages

See the Deployment documentation for production deployment guides.

Package Scripts

ZeroStarter includes many useful scripts defined in package.json:20-35:

Script	Description
`bun dev`	Start development servers with TUI
`bun build`	Build all packages and applications
`bun run db:generate`	Generate Drizzle migrations
`bun run db:migrate`	Run database migrations
`bun run db:studio`	Open Drizzle Studio
`bun run lint`	Lint all packages with Oxlint
`bun run format`	Format code with Oxfmt
`bun run format:check`	Check code formatting
`bun run check-types`	Type-check all packages
`bun run clean`	Remove build artifacts and node_modules
`bun start`	Start production servers

See the Scripts documentation for detailed information about all available commands.

Troubleshooting

Bun installation issues

If Bun fails to install:

# Try the manual installation
curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.7"

# Add to PATH (if not automatic)
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Database connection errors

Common database issues:Connection refused:

Verify PostgreSQL is running: pg_isready
Check the connection string format
Ensure the database exists

Authentication failed:

Verify username and password
Check PostgreSQL user permissions

SSL/TLS errors:

For local databases, remove SSL requirements
For managed databases, ensure SSL is enabled in the connection string

Port conflicts

If ports 3000 or 4000 are in use:Find the process:

lsof -i :3000
lsof -i :4000

Change the ports:

Frontend: Modify web/next/package.json dev script to use next dev -p 3001
Backend: Add HONO_PORT=4001 to .env

Module resolution errors

If you see “Cannot find module” errors:

# Clean everything
bun run clean

# Reinstall dependencies
bun install

# Build shared packages
bun run build --filter='@packages/*'

Turborepo cache issues

Clear Turborepo cache:

# Remove cache directories
rm -rf .turbo
rm -rf node_modules/.cache

# Rebuild
bun run build

Next Steps

Architecture

Understand the tech stack and design decisions.

Project Structure

Learn how the monorepo is organized.

Type-Safe API

Master Hono RPC for end-to-end type safety.

Deployment

Deploy to production on Vercel or other platforms.

Get Started

Core Concepts

Features

Development

Installation

Installation

Prerequisites

Required

Optional

Installation Steps

1. Clone the Repository

2. Install Dependencies

3. Environment Configuration

Essential Variables

OAuth Providers (Optional)

Analytics (Optional)

4. Database Setup

5. Start Development

Verification

API Health Check

Frontend

API Documentation

Type-Safe API Client

Build for Production

Package Scripts

Troubleshooting

Next Steps

Architecture

Project Structure

Type-Safe API

Deployment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Features

Development

​Installation

​Prerequisites

​Required

​Optional

​Installation Steps

​1. Clone the Repository

​2. Install Dependencies

​3. Environment Configuration

​Essential Variables

​OAuth Providers (Optional)

​Analytics (Optional)

​4. Database Setup

​5. Start Development

​Verification

​API Health Check

​Frontend

​API Documentation

​Type-Safe API Client

​Build for Production

​Package Scripts

​Troubleshooting

​Next Steps

Architecture

Project Structure

Type-Safe API

Deployment

Build docs developers (and LLMs) love

Installation

Prerequisites

Required

Optional

Installation Steps

1. Clone the Repository

2. Install Dependencies

3. Environment Configuration

Essential Variables

OAuth Providers (Optional)

Analytics (Optional)

4. Database Setup

5. Start Development

Verification

API Health Check

Frontend

API Documentation

Type-Safe API Client

Build for Production

Package Scripts

Troubleshooting

Next Steps