Local Development

Prerequisites

• Node.js >= 24.0.0
• pnpm >= 9.0.0
• Docker (optional, for database or full-stack testing)

Setup

# Clone the repository
git clone https://github.com/openaigcs/aigcs.git
cd aigcs
 
# Install all dependencies
pnpm install
 
# Build all packages
pnpm build

Running Services

Start each service in a separate terminal:

# Server (API + admin panel)
pnpm --filter @aigcs/server dev
 
# Admin panel (standalone dev server with HMR)
pnpm --filter @aigcs/admin dev
 
# Widget (watch mode)
pnpm --filter @aigcs/widget dev

Environment Variables

Create .env.local in the project root:

echo 'JWT_SECRET=dev-secret-change-in-production' > .env.local
echo 'ENCRYPTION_KEY=dev-encryption-key' >> .env.local

See the Configuration Reference for all available options.

Useful Commands

# Build specific package
pnpm --filter @aigcs/server build
 
# Run tests
pnpm --filter @aigcs/core test
 
# Lint all packages
pnpm lint
 
# TypeScript type checking
pnpm typecheck

pnpm Upgrade Standard

To keep local development versions consistent with build runs inside the Docker container, AIGCS uses corepack to lock the pnpm package manager version. When upgrading pnpm, follow these standard steps:

1. Update package.json: Open the root package.json file and modify the "packageManager" field to your target pnpm version (e.g., "pnpm@11.15.1").
2. Activate Version: Run the corepack command in the root folder to download, activate, and update the locked binaries:

   corepack use pnpm@11.15.1

3. Synchronize Lockfile: Run pnpm install to update pnpm-lock.yaml:

   pnpm install

4. Build & Verify: Run pnpm build to confirm everything builds successfully under the new pnpm release before committing package.json and pnpm-lock.yaml.