Skip to main content
This guide will walk you through setting up ZeroStarter and running your first application.

​
Prerequisites

Before you begin, make sure you have:
  • Bun v1.3.7 or later installed
  • PostgreSQL database running
  • Git installed
If you haven’t installed these yet, check out the Installation Guide for detailed setup instructions.

​
Quick Start in 5 Minutes

1
Clone and Install
2
Clone the repository and install dependencies:
3
bunx gitpick https://github.com/nrjdalal/zerostarter/tree/main
cd zerostarter
bun install
4
Configure Environment
5
Copy the example environment file and add your configuration:
6
cp .env.example .env
7
At minimum, configure these required variables in your .env file:
8
# Generate using: openssl rand -base64 32
BETTER_AUTH_SECRET=your_generated_secret_here

# Generate using: bunx pglaunch -k
POSTGRES_URL=postgresql://user:password@localhost:5432/database
9
Use openssl rand -base64 32 to generate a secure random secret for BETTER_AUTH_SECRET.
10
Set Up Database
11
Generate the database schema and run migrations:
12
bun run db:generate
bun run db:migrate
13
Start Development Server
14
Launch both frontend and backend in development mode:
15
bun dev
16
This command uses Turborepo to run:
17
  • Next.js frontend on http://localhost:3000
  • Hono backend API on http://localhost:4000
    • 18
    Explore Your Application
    19
    Open your browser and navigate to:
    20
  • Frontend: http://localhost:3000
  • API Documentation: http://localhost:4000/api/docs
  • Health Check: http://localhost:4000/health

    • ​
    What’s Running?

    When you run bun dev, Turborepo orchestrates the following processes:
    The frontend application built with:
    • Next.js 16 for the React framework
    • Tailwind CSS for styling
    • Shadcn UI for components
    • TanStack Query for data fetching
    • Better Auth client for authentication
    The frontend automatically connects to the backend API using the type-safe Hono RPC client.
    The backend API server featuring:
    • Hono web framework
    • Drizzle ORM for database queries
    • Better Auth for authentication
    • Scalar API documentation at /api/docs
    • Rate limiting with configurable limits
    • OpenAPI auto-generated specification
    All API routes are type-safe and automatically inferred on the frontend.

    ​
    Understanding the Development Workflow

    ​
    Making Your First Change

    Let’s make a simple change to see hot reloading in action:
    1

    Modify the Frontend

    Open web/next/src/app/page.tsx and make a change to the homepage.The page will automatically reload in your browser.
    2

    Add a New API Route

    Create a new route in api/hono/src/routers/:
    import { Hono } from 'hono'

const app = new Hono()

app.get('/hello', (c) => {
  return c.json({ message: 'Hello from ZeroStarter!' })
})

export default app
    The API will automatically restart with your changes.
    3

    Call the API from Frontend

    Use the type-safe client in your Next.js component:
    import { apiClient } from '@/lib/api/client'

const response = await apiClient.hello.$get()
const data = await response.json()
console.log(data.message) // Fully typed!

    ​
    Available Scripts

    Here are the most commonly used commands: 
    # Start development servers with Turbo TUI
bun dev

# Run type checking across all packages
bun run check-types

# Format code with Oxfmt
bun run format

# Lint code with Oxlint
bun run lint

    ​
    Project Structure Overview

    ZeroStarter uses a monorepo structure organized with Turborepo: 
    zerostarter/
├── api/
│   └── hono/              # Backend API (Hono)
├── web/
│   └── next/              # Frontend app (Next.js)
└── packages/
    ├── auth/              # Shared authentication (Better Auth)
    ├── db/                # Database schema (Drizzle ORM)
    ├── env/               # Environment variables
    └── tsconfig/          # TypeScript config

    Learn More

    Explore the detailed project structure and organization

    ​
    Next Steps

    Now that you have ZeroStarter running, explore these guides:

    Architecture

    Understand the tech stack and architectural decisions

    Type-Safe API

    Learn how to use the end-to-end type-safe API client

    Authentication

    Set up OAuth providers and user authentication

    Database

    Work with the database using Drizzle ORM

    ​
    Getting Help

    If you run into any issues:
    Star the repository if you find ZeroStarter helpful!