Skip to main content

​
Quick Start

Get ZeroStarter running on your local machine in just a few minutes. This guide will walk you through cloning the template, installing dependencies, and starting the development servers.

​
Prerequisites

Before you begin, make sure you have:
  • Bun v1.3.7 or higher installed
  • PostgreSQL database (local or remote)
  • Git for version control
ZeroStarter uses Bun as its primary runtime and package manager. If you haven’t installed Bun yet, run:
curl -fsSL https://bun.sh/install | bash

​
Step 1: Clone the Template

Use gitpick to clone ZeroStarter without the git history: 
bunx gitpick https://github.com/nrjdalal/zerostarter/tree/main
cd zerostarter
gitpick gives you a clean copy of the repository without the commit history, perfect for starting fresh.

​
Step 2: Install Dependencies

Install all workspace dependencies using Bun: 
bun install
This will install dependencies for all packages in the monorepo (api, web, and shared packages).

​
Step 3: Set Up Environment Variables

Copy the example environment file and configure your variables: 
cp .env.example .env
Open .env and configure the essential variables:
1

Generate Auth Secret

Generate a secure secret for Better Auth:
openssl rand -base64 32
Add it to .env:
BETTER_AUTH_SECRET="your-generated-secret"
2

Configure Database

Add your PostgreSQL connection string:
POSTGRES_URL="postgresql://user:password@localhost:5432/zerostarter"
Need a quick database? Use bunx pglaunch -k to generate a free PostgreSQL URL from services like Neon or Supabase.
3

Set Application URLs

Configure your development URLs (defaults work for local development):
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_API_URL=http://localhost:4000
HONO_APP_URL=http://localhost:4000
HONO_TRUSTED_ORIGINS=http://localhost:3000
OAuth providers (GitHub, Google) are optional for development. You can configure them later by adding the respective client IDs and secrets.

​
Step 4: Set Up the Database

Generate and run database migrations: 
bun run db:generate
This will:
  1. Build the environment package
  2. Generate Drizzle ORM migrations from your schema
  3. Apply migrations to your database
You can explore your database using Drizzle Studio:
bun run db:studio
This opens a web interface at https://local.drizzle.studio

​
Step 5: Start Development Servers

Start all development servers with a single command: 
bun dev
This command uses Turborepo to:
  • Build shared packages (auth, db, env)
  • Start the Hono API server on http://localhost:4000
  • Start the Next.js frontend on http://localhost:3000
  • Enable hot reloading for all packages
Turborepo’s TUI (Text User Interface) gives you a beautiful dashboard showing logs from all running services. Press Ctrl+C to stop all servers.

​
Step 6: Verify Installation

Open your browser and verify everything is working:
1

Check Frontend

Visit http://localhost:3000 to see the Next.js application.
2

Check API

Visit http://localhost:4000/api/health to verify the API is running.You should see:
{
  "data": {
    "message": "ok",
    "version": "0.0.14",
    "environment": "local"
  }
}
3

Explore API Docs

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

​
What’s Next?

Explore the Architecture

Learn about the tech stack and monorepo structure.

Detailed Installation

Configure OAuth providers, analytics, and other integrations.

Type-Safe API

Learn how to use Hono RPC for end-to-end type safety.

Project Structure

Understand how the monorepo is organized.

​
Common Commands

Here are the most frequently used commands:
CommandDescription
bun devStart all development servers
bun buildBuild all packages and applications
bun run db:generateGenerate database migrations
bun run db:migrateRun database migrations
bun run db:studioOpen Drizzle Studio
bun run lintLint all packages
bun run formatFormat code with Oxfmt
bun run check-typesType-check all packages
See the Scripts documentation for a complete list of available commands.

​
Troubleshooting

If ports 3000 or 4000 are already in use, you can change them:
  • Frontend: Edit web/next/package.json and modify the dev script
  • Backend: Change HONO_PORT in your environment variables
Verify your POSTGRES_URL is correct and the database is running:
psql $POSTGRES_URL -c "SELECT 1;"
Clean and reinstall dependencies:
bun run clean
bun install

​
Need Help?

If you encounter any issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us