Development Guide

Development Guide

This guide covers the detailed development setup and workflow for Cosella.

Prerequisites

• Node.js: v22.0.0 or higher
• pnpm: v9.0.0 or higher
• Git: v2.30.0 or higher
• VS Code: Recommended editor

Setup

1. Clone and Install

git clone https://github.com/cosella/cosella.git
cd cosella
pnpm install

2. Environment Variables

Create .env.local in the root:

# API Configuration
VITE_API_URL=http://localhost:3000
VITE_WS_URL=ws://localhost:3000

# Sentry (optional)
VITE_SENTRY_DSN=

# Feature Flags
VITE_FEATURE_NEW_DASHBOARD=true

3. Start Development

# Start all apps
pnpm dev

# Or start specific apps
pnpm --filter @cosella/dashboard dev
pnpm --filter @cosella/admin dev
pnpm --filter @cosella/docs dev

Project Structure

Apps

App	Port	Description
Dashboard	5173	Sales rep daily driver
Admin	5174	Internal admin panel
Docs	4322	Documentation site
Marketing	4321	Public landing page
Storybook	6006	Component stories

Packages

Package	Purpose
@cosella/ui	UI components
@cosella/tokens	Design tokens
@cosella/domain	Domain models
@cosella/api-client	API client

Development Commands

Build

# Build all
pnpm build

# Build specific app
pnpm --filter @cosella/dashboard build

Test

# Run all tests
pnpm test

# Run specific package tests
pnpm --filter @cosella/ui test

# Run with coverage
pnpm test -- --coverage

Type Check

# Check all
pnpm typecheck

# Check specific package
pnpm --filter @cosella/ui typecheck

Lint

# Lint all
pnpm lint

# Lint and fix
pnpm lint --fix

Code Generation

New Package

pnpm gen package

New Component

pnpm gen component

New ADR

Create manually in apps/docs/src/content/docs/engineering/adr-NNNN.mdx.

Git Workflow

Branch Naming

• feature/my-feature - New features
• fix/my-bug - Bug fixes
• docs/my-docs - Documentation updates
• refactor/my-refactor - Code refactoring

Commits

Follow Conventional Commits:

feat(ui): add new Button variant
fix(api-client): handle network errors
docs(readme): update installation guide

Pre-commit Hooks

Automatically runs:

• lint-staged: ESLint + Prettier on staged files
• commitlint: Validates commit messages

IDE Setup

VS Code Extensions

• ESLint (dbaeumer.vscode-eslint)
• Prettier (esbenp.prettier-vscode)
• Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)
• TypeScript Importer (ms-vscode.vscode-typescript-next)

VS Code Settings

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

Debugging

VS Code Launch Configurations

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Dashboard",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/vite",
      "args": ["--config", "apps/dashboard/vite.config.ts"],
      "console": "integratedTerminal"
    }
  ]
}

Browser DevTools

• React DevTools: Inspect component tree
• TanStack Query DevTools: Inspect cache state
• Network Tab: Monitor API calls

Performance

Bundle Analysis

# Analyze bundle size
pnpm build -- --analyze

Lighthouse

Run Lighthouse audits in Chrome DevTools.

Troubleshooting

Common Issues

Port Conflicts

# Find process using port
lsof -ti:5173

# Kill process
kill -9 <PID>

Type Errors

# Clear TypeScript cache
rm -rf node_modules/.cache
pnpm install

Build Failures

# Clean build
rm -rf dist
rm -rf node_modules/.cache
pnpm build

Next Steps

• Testing Strategy - Testing best practices
• Releases - Release process