Skip to main content

​
Prerequisites

  • Node.js 22+
  • pnpm 9+ (corepack enable && corepack prepare pnpm@9.12.1)
  • PostgreSQL (local install, or a Neon project for cloud-hosted dev)
  • OpenAI API key

​
Install Dependencies

pnpm install

​
Environment Variables

Copy .env.example and configure for your local setup: 
cp .env.example apps/web-app/.env.local
See Quickstart for the minimum required variables.

​
Build

# Build all packages
pnpm build

# Type check everything
pnpm typecheck

# Type check a specific package
pnpm --filter @whilst/web-app typecheck

​
Run Locally

# Web app (Next.js dev server)
pnpm --filter @whilst/web-app dev

# Job worker (local Lambda emulation)
pnpm --filter @whilst/job-worker dev

​
Package Commands

Use pnpm --filter <package> to run commands in specific packages: 
# Add a dependency
pnpm --filter @whilst/web-app add lodash

# Run tests for a package
pnpm --filter @whilst/tenant-store test

# Lint a package
pnpm --filter @whilst/web-app lint

​
Cross-Package Imports

All packages use the @whilst/ scope. Import shared code like: 
import { TenantStore } from '@whilst/tenant-store';
import { SlackClient } from '@whilst/communication-slack';

​
Conventions

  • pnpm only — do not use npm or yarn
  • Database access goes through packages/tenant-store
  • Real-time events use publishEvent() (batching is automatic)
  • Single changelog at /CHANGELOG.md — always update it