Getting Started

Prerequisites

Node.js 24.x (LTS Krypton) is pinned in .nvmrc and .node-version. pnpm is pinned as packageManager: 11.24.0.

nvm install lts/krypton
nvm alias default lts/krypton
nvm use
corepack enable
corepack prepare pnpm@11.24.0 --activate

Setup

npx create-basilic@latest my-app
cd my-app
pnpm run setup

Or clone this repository / GitHub Use this template, then cd into it. After fork lists what to replace when the copy is your product. Forks are for contributing upstream.

setup installs dependencies, git hooks, security tools, and database tooling. It also copies .env.<qualifier>.example templates to gitignored dest files when those dest files are missing. Copied local env sets ALLOW_TEST=true so test@test.ai works without Resend. Edit the copied files to set paid secrets. setup does not start Postgres.

pnpm --filter @repo/api db:start
pnpm reset
pnpm dev

• API: http://localhost:3001 (GET /health, /reference)
• Web: http://localhost:3000 — first login is /auth/login with test@test.ai (copied env has ALLOW_TEST=true; Resend optional)
• Docs: hosted basilic-docs; in this repo pnpm --filter @repo/docu dev (http://localhost:3002). Generated projects use docs/basilic/ instead.
• Mobile: pnpm --filter @repo/mobile start

Apps: apps/api (Fastify 5), apps/web (Next.js 16), apps/mobile (Expo 57), apps/docu (Fumadocs).

Packages: core, react, ui, utils, error, email, cli. Catalog: Packages.

Local Postgres is Supabase CLI. db:start then pnpm reset (repo root) before pnpm dev. See ADR 008 and Product Ready.

Next

• Product Ready — fork-and-run bar (not CI green)
• After fork — template vs fork, identity, CI secrets, FIRST overlays
• Dev Environments — ports, remote, Expo
• AI Workflow — Cursor-first; FIRST / _first/ load order
• FIRST adopter pack: repo _first/README.md (stations and overlays; not a second docs site)
• Cursor Setup — indexed docs and MCP
• Cursor Skills — versioned tech skills and slash workflows
• Architecture