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

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#prerequisites) and enforced in [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:

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:

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.

2. Install Dependencies

From the repository root, install all workspace dependencies:

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:

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) "scripts" section.

4. Build the Entire Project

Execute the main build command:

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), is:

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

Turbo respects dependency graphs defined in [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:

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:

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:

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) — bundler configuration
• [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) — application entry point

Optional: Generate a New Plugin

To scaffold a new integration package:

pnpm run generate:plugin MyPluginName

This executes [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:

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).

Complete Build Pipeline Example

# 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)	Workspace scripts, dependencies, and pnpm configuration
[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)	Shared TypeScript compiler options
[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)

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) 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) 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 and dependency tree. According to the repository structure, you must install dependencies separately before running pnpm build or pnpm dev within the explorer/ directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}