Installation

Get Init running locally in a few minutes.

PrerequisitesCopy Anchor Link

• Node.js v24+ - Download Node.js
• pnpm v12 - Fast, disk space efficient package manager
• Git
• macOS on Apple silicon, or Linux - Local Postgres runs natively through the Supabase CLI (installed by pnpm install). It needs macOS 14+ or glibc 2.35+; Intel Macs and Windows aren't supported
• Rust - Only for the desktop app: install with rustup, which picks up the version apps/desktop/rust-toolchain.toml pins. Linux also needs WebKitGTK and the other Tauri prerequisites; macOS needs only the Xcode command line tools

Install pnpmCopy Anchor Link

npm install -g pnpm

Or the official installer:

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

VerifyCopy Anchor Link

node --version   # v24+
pnpm --version   # v12
git --version
cargo --version  # desktop app only: rustup fetches the pinned version on first build

Quick StartCopy Anchor Link

1. Clone the RepositoryCopy Anchor Link

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

2. Install DependenciesCopy Anchor Link

pnpm install

3. Environment SetupCopy Anchor Link

One .env file at the repo root drives everything:

cp .env.example .env

Fill in as needed:

• POSTGRES_URL - leave it out for local dev: pnpm db:start writes it into .env.local, which wins over .env
• 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 SetupCopy Anchor Link

Start local Postgres and push the schema:

pnpm db:start   # local Supabase; writes this checkout's POSTGRES_URL into .env.local
pnpm db:push    # drizzle-kit push

The first start downloads Postgres (~400 MB, cached after that). Every git branch gets its own database on its own port, so a new branch starts empty: run pnpm db:start && pnpm db:push there.

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

5. Trim the Starter (Optional)Copy Anchor Link

pnpm bootstrap is the one-command alternative to steps 3–4: it writes .env, starts Postgres, 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 DevelopmentCopy Anchor Link

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 OverviewCopy Anchor Link

init/
├── apps/
│   ├── web/           # Next.js web app (these docs live here)
│   ├── mobile/        # Expo mobile app
│   ├── extension/     # Chrome extension (WXT)
│   └── desktop/       # Tauri desktop app
├── packages/
│   ├── permissions/   # Client-safe auth helpers: role permissions, slugify
│   ├── contract/      # oRPC contract shared by server and clients
│   ├── service/       # oRPC implementation + better-auth
│   ├── db/            # Drizzle schema + local Supabase config
│   └── ui/            # Shared UI components
└── package.json       # Root workspace scripts

Available ScriptsCopy Anchor Link

DevelopmentCopy Anchor Link

• pnpm dev - All apps
• pnpm dev:web / pnpm dev:mobile / pnpm dev:extension - One app
• pnpm dev:desktop - The desktop shell, with the web app it opens

DatabaseCopy Anchor Link

• pnpm db:start / pnpm db:stop - Local Postgres (Supabase CLI)
• 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 QualityCopy Anchor Link

• pnpm lint / pnpm lint:fix - oxlint
• pnpm format / pnpm format:fix - oxfmt, and cargo fmt for the desktop app
• pnpm typecheck - TypeScript, and clippy for the desktop app
• pnpm test - node:test, and cargo test for the desktop app
• pnpm verify - typecheck · lint · format · test (the CI gate)

BuildCopy Anchor Link

• pnpm build - Build all packages (the desktop app's release binary included)
• pnpm -F @repo/desktop package - Bundle the desktop app (.app and .dmg on macOS)

TroubleshootingCopy Anchor Link

Port already in use - Free port 3000. Postgres never clashes: the Supabase CLI gives each checkout and branch its own port and pnpm db:start writes it into .env.local.

pnpm install fails

pnpm store prune
pnpm install

Database connection issues - Start this branch's database, which also points .env.local at it:

pnpm db:start
pnpm -F db status   # what the CLI is running for this checkout

Type errors

pnpm build

Next StepsCopy Anchor Link

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