Skip to content
Cosella Cosella Engineering Docs

Installation

Installation

Section titled “Installation”

This guide will help you set up the Cosella development environment on your machine.

Prerequisites

Section titled “Prerequisites”
  • Node.js: v22.0.0 or higher (recommended: v22.x LTS)
  • pnpm: v9.0.0 or higher
  • Git: v2.30.0 or higher

Quick Setup

Section titled “Quick Setup”

1. Clone the Repository

Section titled “1. Clone the Repository”
Terminal window
git clone https://github.com/cosella/cosella.git
cd cosella

2. Install Dependencies

Section titled “2. Install Dependencies”
Terminal window
pnpm install

3. Verify Installation

Section titled “3. Verify Installation”
Terminal window
pnpm typecheck
pnpm lint
pnpm test

Development Workflow

Section titled “Development Workflow”

Start All Apps

Section titled “Start All Apps”
Terminal window
pnpm dev

Start Specific Apps

Section titled “Start Specific Apps”
Terminal window
# Dashboard (sales rep UI) — port 5173
pnpm --filter @cosella/dashboard dev


# Admin panel — port 5174
pnpm --filter @cosella/admin dev


# Documentation site — port 4322
pnpm --filter @cosella/docs dev


# Marketing site — port 4321
pnpm --filter @cosella/marketing dev


# Storybook (component library) — port 6006
pnpm --filter @cosella/storybook dev

Build

Section titled “Build”
Terminal window
# Build all packages and apps
pnpm build


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

Test

Section titled “Test”
Terminal window
# Run all tests
pnpm test


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


# Run tests with coverage
pnpm test -- --coverage

Code Generation

Section titled “Code Generation”

Generate a New UI Component

Section titled “Generate a New UI Component”
Terminal window
pnpm gen component

This creates:

  • packages/ui/src/<kebab-name>/<Name>.tsx
  • packages/ui/src/<kebab-name>/<Name>.test.tsx
  • Export added to packages/ui/src/index.ts

Generate a New Package

Section titled “Generate a New Package”
Terminal window
pnpm gen package

This creates:

  • packages/<name>/package.json
  • packages/<name>/tsconfig.json
  • packages/<name>/src/index.ts

Regenerate API Client

Section titled “Regenerate API Client”
Terminal window
pnpm gen:api

Regenerates packages/api-client/src/api.gen.ts from the OpenAPI spec.

IDE Setup

Section titled “IDE Setup”

VS Code

Section titled “VS Code”

Install the following extensions:

  • ESLint (dbaeumer.vscode-eslint)
  • Prettier (esbenp.prettier-vscode)
  • Tailwind CSS IntelliSense (bradlc.vscode-tailwindcss)
  • TypeScript Importer (ms-vscode.vscode-typescript-next)
Section titled “Recommended Settings”
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”

Port Already in Use

Section titled “Port Already in Use”

If you see EADDRINUSE errors, stop any running dev servers:

Terminal window
# Find and kill processes on the port
lsof -ti:5173 | xargs kill -9

Type Errors

Section titled “Type Errors”

Run typecheck to identify issues:

Terminal window
pnpm typecheck

Lint Errors

Section titled “Lint Errors”

Run the linter to fix formatting:

Terminal window
pnpm lint --fix

Build Failures

Section titled “Build Failures”

Clean and rebuild:

Terminal window
rm -rf node_modules/.cache
rm -rf apps/*/dist
pnpm build

Next Steps

Section titled “Next Steps”