Corsair Development Tools and Frameworks: Complete Setup Guide for Contributors

Developing Corsair requires Node.js 22+, pnpm 10+, and a TypeScript-first toolchain including TurpoRepo, Biome, and tsx.

Corsair is a TypeScript-first monorepo built for extensibility. Whether you're creating a new plugin or contributing to core features, understanding the required Corsair development tools and frameworks ensures a frictionless workflow. This guide covers every prerequisite, explains why each tool matters, and provides copy-paste commands to get started.

Core Prerequisites

Node.js 22 or Higher

Node.js ≥ 22 is mandatory because Corsair uses the --experimental-strip-types flag for executing TypeScript directly. This feature eliminates pre-compilation overhead for scripts like scripts/generate-plugin.ts.

# Install and activate Node.js 22

nvm install 22 && nvm use 22

# Verify version

node --version  # Should output v22.x.x or higher

pnpm 10+ as Package Manager

Every package.json script assumes pnpm is available. The workspace relies on pnpm's content-addressable store and strict peer dependency handling.

# Install pnpm globally

npm i -g pnpm@10

# Verify installation

pnpm --version  # Should output 10.x.x or higher

Build and Orchestration Tools

TurpoRepo for Monorepo Workflows

Turbo (turbo CLI) orchestrates builds, tests, and linting across all packages in packages/*. The root package.json defines filtered commands like:

// package.json (excerpt)
"scripts": {
  "build": "turbo --filter \"./packages/*\" build",
  "test": "turbo --filter \"./packages/*\" test",
  "lint": "turbo --filter \"./packages/*\" lint"
}

Turbo's task pipeline ensures dependent packages rebuild automatically when upstream sources change.

TypeScript with Strict Configuration

The entire codebase uses strict TypeScript as defined in tsconfig.base.json. Type checking runs via tsc --build across workspace references.

# Type-check the entire monorepo

pnpm typecheck

The base configuration enforces:

• strict: true
• module: "NodeNext"
• target: "ES2022"

tsx for Script Execution

The tsx CLI runs TypeScript scripts without transpilation. This powers internal tooling in scripts/.

# Generate plugin documentation directly

tsx scripts/generate-plugin-docs.ts

# Validate all plugin structures (CI use)

tsx scripts/validate-plugins.ts

Code Quality and Formatting

Biome for Linting and Formatting

Biome (@biomejs/biome) replaces ESLint and Prettier with a unified, fast toolchain. Configuration lives in biome.json at the repository root.

# Check for lint errors

pnpm lint

# Auto-fix issues and format code

pnpm lint:fix
pnpm format

Biome handles import sorting, unused variable detection, and consistent code style across all packages.

Release and Version Management

Bumpp for Automated Releases

Bumpp handles version bumping, changelog generation, and git tagging. The release:canary script demonstrates its integration:

# Publish a canary release

pnpm release:canary

This command bumps versions, builds all packages, and publishes with the canary dist-tag.

Database and Runtime Dependencies

better-sqlite3 for Local Persistence

The core corsair package depends on better-sqlite3 for local state management. The root package.json includes a pnpm.overrides block ensuring native compilation succeeds across platforms.

// package.json (excerpt)
"pnpm": {
  "overrides": {
    "better-sqlite3": "11.5.0"
  }
}

This override prevents version drift that could break native module bindings.

Optional Bun Runtime Support

Bun is declared as a type-only dependency in tsconfig.base.json for teams deploying to Bun environments. This does not affect Node.js workflows.

Quick Start: Full Development Setup

# 1. Clone your fork

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

# 2. Install dependencies

pnpm install

# 3. Verify setup by running the full pipeline

pnpm typecheck
pnpm lint
pnpm build

# 4. Scaffold a new plugin (requires Node 22+)

pnpm run generate:plugin MyNewIntegration

Key Configuration Files

File	Purpose	Location
package.json	Workspace scripts, dev dependencies, pnpm configuration	/package.json
CONTRIBUTING.md	Official contributor setup instructions	/CONTRIBUTING.md
tsconfig.base.json	Shared strict TypeScript settings	/tsconfig.base.json
scripts/generate-plugin.ts	Plugin scaffolding CLI	/scripts/generate-plugin.ts
scripts/validate-plugins.ts	CI plugin validation	/scripts/validate-plugins.ts

Summary

• Node.js ≥ 22 is non-negotiable due to --experimental-strip-types usage in scripts/generate-plugin.ts
• pnpm ≥ 10 manages all workspace dependencies and scripts
• TurpoRepo (turbo) orchestrates parallel builds across packages/*
• Biome provides unified linting and formatting
• tsx enables direct TypeScript execution without pre-compilation
• better-sqlite3 powers local persistence in the core package

These Corsair development tools and frameworks combine into a cohesive toolchain where pnpm install followed by pnpm build prepares everything needed for plugin development.

Frequently Asked Questions

Do I need to install TypeScript globally?

No. TypeScript is a devDependency in the root package.json. Run pnpm typecheck or pnpm build to use the workspace-installed version. Global installation may cause version mismatches.

Can I use npm or yarn instead of pnpm?

No. The Corsair monorepo uses pnpm-specific features including pnpm.overrides for native dependencies and workspace protocols. All scripts in package.json assume pnpm is available.

What happens if I use Node.js 20 instead of 22?

Plugin generation will fail. The generate:plugin script in scripts/generate-plugin.ts requires Node's --experimental-strip-types flag, which only exists in Node 22 and later. Other tasks may work but are unsupported.

Is Docker required for Corsair development?

No. While better-sqlite3 compiles native code, pnpm handles this automatically during pnpm install. No containerization is needed for standard development workflows.

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