How to Get Started Contributing to Corsair: A Complete Guide for New Contributors

To start contributing to Corsair, claim an integration on the OSS page, open a descriptive issue, fork the monorepo, scaffold a plugin with pnpm run generate:plugin, implement your endpoints and webhooks, test locally in demo/testing, and submit a PR following the repository's PLUGIN_PR_RULES.md.

Corsair is an open-source integration framework built as a TypeScript monorepo. Whether you want to add a new third-party integration, improve the core library (packages/corsair), or enhance documentation and tooling, this guide walks you through the exact workflow used by current contributors — all grounded in the source code structure and maintainer guidelines.

---

Understanding the Corsair Monorepo Architecture

Before writing code, you need to know how the repository is organized. According to CONTRIBUTING.md, code falls into three package categories:

Layer	Purpose	Key Files
Core Framework	Shared types, authentication, error handling, and plugin registration API	packages/corsair/core/constants.ts, packages/corsair/core/index.ts
Plugin Packages	Individual integrations, each with endpoints, webhooks, and schemas	packages/<name>/, scaffolded by scripts/generate-plugin.ts
Demo / Test Sandbox	Local test harness for end-to-end plugin validation	demo/testing/src/server/corsair.ts, demo/testing/src/scripts/test-script.ts
CLI & UI	Development utilities and local studio for inspecting instances	packages/cli/, packages/studio/

The core integration framework in packages/corsair exports the plugin registration API that every integration consumes. The plugin generator at scripts/generate-plugin.ts creates standardized package scaffolds so all integrations follow consistent patterns.

---

Step-by-Step: Contributing to Corsair

Claim Your Integration

Visit https://corsair.dev/oss to find unclaimed integrations. The maintainers emphasize coordination: create an issue before starting significant work to avoid duplicate effort and validate API design decisions upfront.

Your issue should include:

• API documentation links
• Authentication model (OAuth 2.0, API key, etc.)
• Required endpoints and webhook support needs

Use the templates in .github/ISSUE_TEMPLATE/ to ensure completeness.

Fork and Clone the Repository

git clone https://github.com/<your-username>/corsair.git corsair-<integration-slug>
cd corsair-<integration-slug>
pnpm install

The project uses pnpm workspaces for dependency management across the monorepo.

Generate a Plugin Scaffold

pnpm run generate:plugin <PluginName>

This command invokes scripts/generate-plugin.ts, which creates:

• package.json and tsconfig.json
• Endpoint stubs in endpoints/
• Webhook scaffolding in webhooks/
• Database schema files in schema/
• A complete test suite

The generator also updates packages/corsair/core/constants.ts to register your provider in the BaseProviders array and AllProviders type union.

Implement Endpoints

Edit the generated client.ts to add real API calls. Define your input/output schemas in endpoints/types.ts and implement handlers in endpoints/example.ts.

Here's the pattern from the scaffold for a Slack channels.list endpoint:

// packages/slack/endpoints/example.ts
import { makeSlackRequest } from '../client';
import type { SlackEndpoints } from '..';

export const getChannels: SlackEndpoints['channelsList'] = async (ctx, input) => {
  const response = await makeSlackRequest<SlackEndpointOutputs['channelsList']>(
    'conversations.list',
    ctx.key,
    { query: { limit: input.limit } },
  );

  await logEventFromContext(ctx, 'slack.channels.list', { ...input }, 'completed');
  return response;
};

Add Webhook Support (Optional)

If your integration supports webhooks, implement:

• Payload validation in webhooks/types.ts
• Matcher function: create<Plugin>Match()
• Signature verification: verify<Plugin>WebhookSignature()
• Registration in webhooks/example.ts

Define Database Schema (Optional)

For integrations needing persistence, edit schema/database.ts using Zod schemas, then export from schema/index.ts.

Write Tests

Create tests in **/*.test.ts files. Ensure schema.test.ts passes — this validates your type definitions against expected structures.

Test Locally in the Sandbox

cd demo/testing
pnpm test

The sandbox loads your plugin through demo/testing/src/server/corsair.ts:

// demo/testing/src/server/corsair.ts
import { slack } from '../../packages/slack';

export const corsair = createCorsairInstance({
  plugins: [slack()],
});

Manual testing runs via demo/testing/src/scripts/test-script.ts.

Lint, Type-Check, and Build

pnpm lint
pnpm typecheck
pnpm build

Submit Your Pull Request

Follow the requirements in .github/PLUGIN_PR_RULES.md:

• Link to your issue
• Describe the API surface and schema decisions
• Note any webhook implementation details
• Include a demo video if requested

---

Essential Files for Contributors

Path	What You'll Find
CONTRIBUTING.md	Full workflow, branch strategy, commit format
AGENTS.md	Agent-centric view of repository layout
scripts/generate-plugin.ts	The generator script you invoke with pnpm run generate:plugin
packages/corsair/core/constants.ts	Provider registry (BaseProviders, AllProviders)
demo/testing/src/server/corsair.ts	Plugin registration example for local testing
demo/testing/src/scripts/test-script.ts	Manual end-to-end test entry point
.github/PLUGIN_PR_RULES.md	Formal PR requirements
docs/plugins/README.md	Extended documentation for plugin developers

---

Summary

• Claim early: Check corsair.dev/oss and open an issue before coding
• Scaffold smart: Use pnpm run generate:plugin to create standardized package structures
• Test locally: The demo/testing sandbox validates your integration before PR submission
• Follow rules: Reference .github/PLUGIN_PR_RULES.md for submission requirements
• Core awareness: Understand that packages/corsair/core/constants.ts and scripts/generate-plugin.ts automate much of the boilerplate

---

Frequently Asked Questions

Do I need to manually edit core files when adding a plugin?

No — scripts/generate-plugin.ts automatically updates packages/corsair/core/constants.ts to register your provider in BaseProviders and AllProviders. The generator handles the boilerplate so you can focus on API implementation.

What testing is required before submitting a PR?

Run pnpm test in demo/testing to verify your plugin registers correctly and passes end-to-end validation. You also need schema.test.ts passing, plus any custom endpoint tests you add. The maintainers require green CI before review.

Can I contribute without building a full integration?

Yes — the repository explicitly welcomes "PRs for the core library, docs, tooling, and new integration plugins." Documentation improvements, CLI enhancements in packages/cli/, and Studio features in packages/studio/ are all valid contribution paths.

How do I test webhooks during local development?

The demo/testing sandbox supports webhook inspection through the local server configuration in demo/testing/src/server/corsair.ts. Implement your verify<Plugin>WebhookSignature function and use the test script runner to simulate webhook payloads against your matcher logic.

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