Installation

Get Init running locally in a few minutes.

Prerequisites

• Node.js v24+ - Download Node.js
• pnpm v12 - Fast, disk space efficient package manager
• Git
• Docker - Required by local Postgres

Install pnpm

npm install -g pnpm

Or the official installer:

curl -fsSL https://get.pnpm.io/install.sh | sh -

Verify

node --version  # v24+
pnpm --version  # v12
git --version

Quick Start

1. Clone the Repository

git clone https://github.com/kyh/init.git
cd init

2. Install Dependencies

pnpm install

3. Environment Setup

One .env file at the repo root drives everything:

cp .env.example .env

Fill in as needed:

• POSTGRES_URL - defaults to the local Postgres container; leave as-is for local dev
• COMPOSE_PROJECT_NAME - namespaces the local Docker volume so clones don't share one database
• BETTER_AUTH_SECRET - generate with openssl rand -base64 32
• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET - only for GitHub login
• BLOB_READ_WRITE_TOKEN - only for avatar uploads (Vercel Blob). There's no local emulator, so leave it unset offline: the avatar route returns 501 with a pointer and the rest of the app is unaffected.

4. Database Setup

Start local Postgres and push the schema:

pnpm db:start   # Postgres on :54322 (or whatever port .env sets)
pnpm db:push    # drizzle-kit push

Using a hosted database instead? Create one on Vercel Postgres (or any Postgres host), point POSTGRES_URL at it, and run pnpm db:push.

5. Trim the Starter (Optional)

pnpm bootstrap is the one-command alternative to steps 3–4: it starts Postgres, writes .env, pushes the schema, and seeds a dev user (dev@init.local / password), then ends with an interactive checklist — deselect mobile, extension, or desktop and it deletes them cleanly. Pass --yes to keep all apps and run unattended (how a coding agent provisions).

pnpm bootstrap        # interactive
pnpm bootstrap --yes  # headless: keep all apps, no prompts

6. Start Development

pnpm dev        # All apps
pnpm dev:web    # Web only

• Web app: http://localhost:3000
• Drizzle Studio: pnpm -F db studio - browse the database

Project Structure Overview

init/
├── apps/
│   ├── web/           # Next.js web app (these docs live here)
│   ├── mobile/        # Expo mobile app
│   ├── extension/     # Chrome extension (WXT)
│   └── desktop/       # Electron desktop app
├── packages/
│   ├── api/           # oRPC router + better-auth
│   ├── db/            # Drizzle schema + local Postgres compose
│   └── ui/            # Shared UI components
└── package.json       # Root workspace scripts

Available Scripts

Development

• pnpm dev - All apps
• pnpm dev:web / pnpm dev:mobile / pnpm dev:extension / pnpm dev:desktop - One app

Database

• pnpm db:start / pnpm db:stop - Local Postgres container
• pnpm db:push - Push schema to local database
• pnpm db:seed - Seed a dev user + sample data
• pnpm db:push-remote - Push schema to production
• pnpm db:reset - Reset local database, re-push, and re-seed

Code Quality

• pnpm lint / pnpm lint:fix - oxlint
• pnpm format / pnpm format:fix - oxfmt
• pnpm typecheck - TypeScript
• pnpm test - node:test
• pnpm verify - typecheck · lint · format · test (the CI gate)

Build

• pnpm build - Build all packages

Troubleshooting

Port already in use - Free port 3000. For Postgres, pnpm bootstrap picks a free port from 54322 up and records it as POSTGRES_PORT, so a second project on the same machine gets its own.

pnpm install fails

pnpm store prune
pnpm install

Database connection issues - Is Docker running? Then:

pnpm db:start

Type errors

pnpm build

Next Steps

• Agent-Driven Development - provision, seed, and verify with a coding agent
• Local Development - the day-to-day human workflow