Getting Started

Prerequisites

• Node.js >= 22
• pnpm 10.28.0
• (Optional) PostgreSQL or Supabase account

Setup

Install pnpm

If you don't have pnpm installed, install it using one of the following methods:

Using npm:

npm install -g pnpm@10.28.0

Using corepack (recommended):

corepack enable
corepack prepare pnpm@10.28.0 --activate

Using standalone script:

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

Verify your installation:

pnpm --version

Quick Start

1. Clone and Install (2 min)

git clone <repository-url>
cd <project-name>
pnpm install

2. Explore the Running Apps (3 min)

pnpm dev

• API: http://localhost:3001 (GET /health, /reference for docs)
• Docs: http://localhost:3002

3. Understand the Structure (5 min)

Apps: apps/api/ (Fastify backend), apps/docs/ (documentation)

Packages: core/ (generated API client), types/ (domain types), react/ (React Query hooks), ui/ (components)

flowchart TB
  subgraph Apps["Applications"]
    API["apps/api<br/>Fastify backend"]
    Docs["apps/docs<br/>Documentation"]
  end

  subgraph Packages["Shared Packages"]
    Types["@basilic/types<br/>Domain types"]
    Core["@basilic/core<br/>Generated API client"]
    React["@basilic/react<br/>React hooks"]
    UI["@basilic/ui<br/>Components"]
  end

  Types --> Core
  Core --> React
  API -->|OpenAPI| Core
  UI --> Docs

4. Make Your First Change (5 min)

Add a new API endpoint: define contract → implement route → use typed client. See Add an API Endpoint for details.

Next Steps

Understand Core Concepts:

• Monorepo Structure - Package organization
• Code-First APIs - OpenAPI and hey-api pattern
• Portability Strategy - Avoiding vendor lock-in

AI-Driven Development:

• AI Workflow - Recommended development workflow
• Cursor Setup - Configure your IDE

Add Features:

• How-To Guides - Common tasks
• Architecture - Deep technical details

Environment Setup (Optional)

For database features, you'll need PostgreSQL. See Environment Setup Guide.