# How to Build the Corsair Project from Source: A Complete Guide

> Learn to build the Corsair project from source with Node.js and pnpm. This guide covers the TypeScript monorepo build process for all plugin packages.

- Repository: [corsairdev/corsair](https://github.com/corsairdev/corsair)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Building Corsair from source requires Node.js 22+, pnpm 10, and uses turbo to build the TypeScript monorepo across all plugin packages.**

Corsair is an **open-source plugin platform** written in TypeScript and organized as a monorepo. Whether you're contributing a new integration or running the project locally, this guide walks through the complete build process using the exact tooling and scripts defined in the `corsairdev/corsair` repository.

## Prerequisites for Building Corsair

Before cloning, ensure your environment meets the requirements specified in [[`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md)](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md#prerequisites) and enforced in [[`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json)](https://github.com/corsairdev/corsair/blob/main/package.json):

- **Node.js 22 or higher** — required for `--experimental-strip-types` support
- **pnpm 10** — the mandatory package manager; npm and yarn are not supported

Verify your versions:

```bash
node --version  # v22.x.x or higher

pnpm --version  # 10.x.x

```

## Step-by-Step Build Instructions

### 1. Clone the Repository

Fork the repository on GitHub, then clone your fork:

```bash
git clone https://github.com/<your-username>/corsair.git corsair-dev
cd corsair-dev

```

This mirrors the fork-and-local-setup workflow documented in the [Contributing guide](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md#fork-and-local-setup).

### 2. Install Dependencies

From the repository root, install all workspace dependencies:

```bash
pnpm install

```

This creates a shared `node_modules` structure across all packages defined in the monorepo.

### 3. Run Static Checks (Recommended)

Validate code quality before building:

```bash
pnpm lint       # Biome linting across all packages

pnpm typecheck  # tsc --build for type validation

pnpm format     # Biome code formatting

```

These scripts are defined in the root [[`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json)](https://github.com/corsairdev/corsair/blob/main/package.json) `"scripts"` section.

### 4. Build the Entire Project

Execute the main build command:

```bash
pnpm build

```

This delegates to **turbo**, which orchestrates parallel builds across every package in `packages/*`. The underlying command, as configured in [[`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json)](https://github.com/corsairdev/corsair/blob/main/package.json), is:

```json
"build": "turbo --filter \"./packages/*\" build"

```

Turbo respects dependency graphs defined in [[`turbo.json`](https://github.com/corsairdev/corsair/blob/main/turbo.json)](https://github.com/corsairdev/corsair/blob/main/turbo.json), ensuring packages build in the correct order.

### 5. Run the Test Suite

After a successful build, execute all package tests:

```bash
pnpm test

```

Like `pnpm build`, this uses turbo to distribute test execution across the monorepo.

### 6. Start Development Mode

For iterative development with file watching:

```bash
pnpm dev

```

This starts turbo in watch mode, rebuilding packages as you edit source files.

## Building and Running the Explorer UI

The `explorer` workspace contains a **Next.js application** for browsing the plugin catalog. To build it separately:

```bash
cd explorer
pnpm install    # install workspace-specific dependencies

pnpm build      # Next.js production build

pnpm dev        # development server at http://localhost:3000

```

Key configuration files:
- [[`explorer/tsup.config.ts`](https://github.com/corsairdev/corsair/blob/main/explorer/tsup.config.ts)](https://github.com/corsairdev/corsair/blob/main/explorer/tsup.config.ts) — bundler configuration
- [[`explorer/tsconfig.json`](https://github.com/corsairdev/corsair/blob/main/explorer/tsconfig.json)](https://github.com/corsairdev/corsair/blob/main/explorer/tsconfig.json) — TypeScript compiler options
- [[`explorer/src/server.ts`](https://github.com/corsairdev/corsair/blob/main/explorer/src/server.ts)](https://github.com/corsairdev/corsair/blob/main/explorer/src/server.ts) — application entry point

## Optional: Generate a New Plugin

To scaffold a new integration package:

```bash
pnpm run generate:plugin MyPluginName

```

This executes [[`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts)](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts), which creates a complete package structure under `packages/my-plugin-name/` with boilerplate configuration, tests, and build scripts.

## Clean and Reset the Workspace

If dependencies change or builds behave unexpectedly:

```bash
pnpm clean

```

This runs `turbo clean` across all packages and removes `node_modules`, as defined in the root [[`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json)](https://github.com/corsairdev/corsair/blob/main/package.json).

## Complete Build Pipeline Example

```bash

# Clone and enter repository

git clone https://github.com/<your-username>/corsair.git corsair-dev
cd corsair-dev

# Install and validate

pnpm install
pnpm lint
pnpm typecheck

# Build and test

pnpm build
pnpm test

# Start development

pnpm dev

```

## Key Configuration Files

Understanding these files helps when troubleshooting builds or extending the project:

| File | Purpose |
|------|---------|
| [[`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json)](https://github.com/corsairdev/corsair/blob/main/package.json) | Workspace scripts, dependencies, and pnpm configuration |
| [[`turbo.json`](https://github.com/corsairdev/corsair/blob/main/turbo.json)](https://github.com/corsairdev/corsair/blob/main/turbo.json) | Build pipeline orchestration and caching rules |
| [[`tsconfig.base.json`](https://github.com/corsairdev/corsair/blob/main/tsconfig.base.json)](https://github.com/corsairdev/corsair/blob/main/tsconfig.base.json) | Shared TypeScript compiler options |
| [[`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md)](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) | Official onboarding documentation |

## Summary

- **Requirements**: Node.js 22+, pnpm 10 — enforced by the build system
- **Install**: `pnpm install` from repository root resolves all workspace dependencies
- **Build**: `pnpm build` uses turbo to compile all packages in dependency order
- **Develop**: `pnpm dev` enables watch mode for rapid iteration
- **Explore**: The `explorer/` workspace provides a Next.js UI for plugin discovery
- **Extend**: `pnpm run generate:plugin` creates new integration scaffolding via [[`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts)](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts)

## Frequently Asked Questions

### Can I build Corsair with npm or yarn instead of pnpm?

No. The `corsairdev/corsair` repository uses pnpm workspaces and relies on pnpm-specific features. The [[`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json)](https://github.com/corsairdev/corsair/blob/main/package.json) explicitly enforces pnpm 10, and scripts assume pnpm's `node_modules` layout.

### What does the turbo build system do exactly?

**Turbo** is a monorepo task runner that caches build outputs and parallelizes execution. In Corsair, [[`turbo.json`](https://github.com/corsairdev/corsair/blob/main/turbo.json)](https://github.com/corsairdev/corsair/blob/main/turbo.json) defines build dependencies so packages compile in the correct order. Running `pnpm build` executes `turbo --filter "./packages/*" build`, which skips unchanged packages using its cache.

### How do I build a single package instead of everything?

Use turbo's filter syntax from the repository root: `pnpm turbo --filter @corsair/package-name build`. Alternatively, `cd` into the specific package directory and run `pnpm build` there — turbo will still respect the monorepo's dependency graph for that package's upstream requirements.

### Why does the explorer need separate `pnpm install`?

The `explorer` workspace is not part of the main `packages/*` glob that turbo processes for builds. It maintains its own [`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json) and dependency tree. According to the repository structure, you must install dependencies separately before running `pnpm build` or `pnpm dev` within the `explorer/` directory.