Skip to main content

​
Prerequisites

Before installing ZeroStarter, ensure you have the following installed:
  • Bun - v1.3.7 or later (Install Bun)
  • PostgreSQL - A PostgreSQL database instance
  • Git - For cloning the repository

​
Installation Steps

1
Clone the Repository
2
Clone ZeroStarter using gitpick to get the latest template:
3
bunx gitpick https://github.com/nrjdalal/zerostarter/tree/main
cd zerostarter
4
Alternatively, you can use standard git clone:
5
git clone https://github.com/nrjdalal/zerostarter.git
cd zerostarter
6
Install Dependencies
7
Install all workspace dependencies using Bun:
8
bun install
9
This will install dependencies for all packages in the monorepo, including:
10
  • Frontend (Next.js)
  • Backend (Hono)
  • Shared packages (auth, db, env, tsconfig)
    • 11
    Set Up Environment Variables
    12
    Copy the example environment file and configure your settings:
    13
    cp .env.example .env
    14
    Edit the .env file and configure the following required variables:
    15
    Server Variables
    16
    # App URLs
HONO_APP_URL=http://localhost:4000
HONO_TRUSTED_ORIGINS=http://localhost:3000

# Rate Limiting
HONO_RATE_LIMIT=60
HONO_RATE_LIMIT_WINDOW_MS=60000

# Authentication Secret (generate using: openssl rand -base64 32)
BETTER_AUTH_SECRET=your_secret_here

# Database (generate using: bunx pglaunch -k)
POSTGRES_URL=postgresql://user:password@localhost:5432/database
    17
    Client Variables
    18
    # App URLs
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:4000
    19
    Optional OAuth Providers
    20

    GitHub OAuth Setup

    To enable GitHub authentication:
    1. Go to GitHub Developer Settings
    2. Create a new OAuth App
    3. Set Authorization callback URL to: http://localhost:3000/api/auth/callback/github
    4. Add the credentials to your .env:
    GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
    21

    Google OAuth Setup

    To enable Google authentication:
    1. Go to Google Cloud Console
    2. Create a new OAuth 2.0 Client ID
    3. Add authorized redirect URI: http://localhost:3000/api/auth/callback/google
    4. Add the credentials to your .env:
    GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
    22
    Set Up the Database
    23
    Generate and run database migrations:
    24
    bun run db:generate
bun run db:migrate
    25
    These commands will:
    26
  • Generate Drizzle ORM migration files based on your schema
  • Apply migrations to your PostgreSQL database
    • 27
    Make sure your POSTGRES_URL is correctly configured before running migrations.
    28
    Optional: Launch Drizzle Studio
    29
    You can explore and manage your database using Drizzle Studio:
    30
    bun run db:studio
    31
    This opens a web interface at https://local.drizzle.studio for database management.

    ​
    Verify Installation

    To verify everything is set up correctly, start the development server: 
    bun dev
    This will start:
    • Frontend at http://localhost:3000
    • Backend API at http://localhost:4000
    • API Documentation at http://localhost:4000/api/docs
    You should see both services running in the Turbo TUI (Terminal UI).

    ​
    Common Issues

    If you encounter database connection issues:
    1. Verify your POSTGRES_URL is correct
    2. Ensure PostgreSQL is running
    3. Check that the database exists
    4. Verify network connectivity to the database
    Quick database setup using pglaunch:
    bunx pglaunch -k
    If ports 3000 or 4000 are already in use, you can:
    1. Stop the process using the port
    2. Or modify the ports in your .env file:
    HONO_APP_URL=http://localhost:4001
NEXT_PUBLIC_API_URL=http://localhost:4001
    ZeroStarter requires Bun v1.3.7 or later. Update Bun:
    bun upgrade
    Or install a specific version:
    curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.7"

    ​
    Next Steps

    Quick Start

    Follow the quick start guide to build your first feature

    Architecture

    Learn about ZeroStarter’s architecture and tech stack

    Project Structure

    Explore the monorepo structure and organization

    Type-Safe API

    Understand end-to-end type safety with Hono RPC