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

> Learn how to contribute to Corsair. Follow our step-by-step guide to claim integrations, scaffold plugins, test, and submit your first pull request to the corsairdev/corsair repository.

- Repository: [corsairdev/corsair](https://github.com/corsairdev/corsair)
- Tags: getting-started
- Published: 2026-09-01

---

**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](https://github.com/corsairdev/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts), [`packages/corsair/core/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/index.ts) |
| **Plugin Packages** | Individual integrations, each with endpoints, webhooks, and schemas | `packages/<name>/`, scaffolded by [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts) |
| **Demo / Test Sandbox** | Local test harness for end-to-end plugin validation | [`demo/testing/src/server/corsair.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/server/corsair.ts), [`demo/testing/src/scripts/test-script.ts`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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](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

```bash
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

```bash
pnpm run generate:plugin <PluginName>

```

This command invokes [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts), which creates:
- [`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json) and [`tsconfig.json`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts) to register your provider in the `BaseProviders` array and `AllProviders` type union.

### Implement Endpoints

Edit the generated [`client.ts`](https://github.com/corsairdev/corsair/blob/main/client.ts) to add real API calls. Define your input/output schemas in [`endpoints/types.ts`](https://github.com/corsairdev/corsair/blob/main/endpoints/types.ts) and implement handlers in [`endpoints/example.ts`](https://github.com/corsairdev/corsair/blob/main/endpoints/example.ts).

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

```typescript
// 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`](https://github.com/corsairdev/corsair/blob/main/webhooks/types.ts)
- Matcher function: `create<Plugin>Match()`
- Signature verification: `verify<Plugin>WebhookSignature()`
- Registration in [`webhooks/example.ts`](https://github.com/corsairdev/corsair/blob/main/webhooks/example.ts)

### Define Database Schema (Optional)

For integrations needing persistence, edit [`schema/database.ts`](https://github.com/corsairdev/corsair/blob/main/schema/database.ts) using Zod schemas, then export from [`schema/index.ts`](https://github.com/corsairdev/corsair/blob/main/schema/index.ts).

### Write Tests

Create tests in `**/*.test.ts` files. Ensure [`schema.test.ts`](https://github.com/corsairdev/corsair/blob/main/schema.test.ts) passes — this validates your type definitions against expected structures.

### Test Locally in the Sandbox

```bash
cd demo/testing
pnpm test

```

The sandbox loads your plugin through [`demo/testing/src/server/corsair.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/server/corsair.ts):

```typescript
// 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`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/scripts/test-script.ts).

### Lint, Type-Check, and Build

```bash
pnpm lint
pnpm typecheck
pnpm build

```

### Submit Your Pull Request

Follow the requirements in [`.github/PLUGIN_PR_RULES.md`](https://github.com/corsairdev/corsair/blob/main/.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`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) | Full workflow, branch strategy, commit format |
| [`AGENTS.md`](https://github.com/corsairdev/corsair/blob/main/AGENTS.md) | Agent-centric view of repository layout |
| [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts) | The generator script you invoke with `pnpm run generate:plugin` |
| [`packages/corsair/core/constants.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts) | Provider registry (`BaseProviders`, `AllProviders`) |
| [`demo/testing/src/server/corsair.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/server/corsair.ts) | Plugin registration example for local testing |
| [`demo/testing/src/scripts/test-script.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/scripts/test-script.ts) | Manual end-to-end test entry point |
| [`.github/PLUGIN_PR_RULES.md`](https://github.com/corsairdev/corsair/blob/main/.github/PLUGIN_PR_RULES.md) | Formal PR requirements |
| [`docs/plugins/README.md`](https://github.com/corsairdev/corsair/blob/main/docs/plugins/README.md) | Extended documentation for plugin developers |

---

## Summary

- **Claim early**: Check [corsair.dev/oss](https://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`](https://github.com/corsairdev/corsair/blob/main/.github/PLUGIN_PR_RULES.md) for submission requirements
- **Core awareness**: Understand that [`packages/corsair/core/constants.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts) and [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts) automatically updates [`packages/corsair/core/constants.ts`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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`](https://github.com/corsairdev/corsair/blob/main/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.