# Corsair Key Modules and Packages to Focus On First: A Developer's Guide

> Focus on Corsair core and client modules first for initialization, tenant handling, and plugin wiring. A developer's guide to Corsair packages.

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

---

**Start with [`packages/corsair/core/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/index.ts) (the `createCorsair` factory) and [`packages/corsair/client/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/client/index.ts) (the client builder)—these two modules contain the entire initialization flow, tenant handling, and plugin wiring that powers every Corsair integration.**

Corsair is organized as a **monorepo** where the core library lives in `packages/corsair` and each third-party integration ships as a separate plugin under `packages/<plugin>/`. Whether you're building your first integration or extending the framework, mastering the core modules first will dramatically accelerate your productivity. This guide maps out the essential files, explains how they connect, and provides runnable code examples from the `corsairdev/corsair` source code.

## The Public API Entry Point: [`packages/corsair/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/index.ts)

The file [`packages/corsair/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/index.ts) re-exports everything consumers need: `createCorsair`, `CorsairClient`, `CorsairTenantWrapper`, and type definitions. This is the **surface area** you'll interact with as a library user.

Understanding this file reveals the high-level contract—what's public, what's typed, and how the pieces are named. From here, trace inward to the implementation details.

## The Core Factory: [`packages/corsair/core/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/index.ts)

The **`createCorsair`** factory function is the heart of the framework. Located in [`packages/corsair/core/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/index.ts), it:

- Accepts a configuration object with plugins, database settings, a **key-encryption-key (kek)**, and optional hub configuration
- Builds the internal `CorsairInternalConfig` object containing resolved plugins, tenancy flags, permissions, and hub settings
- Attaches this config to the client via the internal symbol `CORSAIR_INTERNAL`
- Returns either a bare client (single-tenant) or a `CorsairTenantWrapper` (multi-tenant)

This is where **multi-tenancy** is implemented. When `multiTenancy: true` is set, the factory returns a wrapper exposing `withTenant(tenantId)`, which produces a tenant-scoped client via the `buildCorsairClient` internal helper.

## The Client Builder: [`packages/corsair/client/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/client/index.ts)

Module [`packages/corsair/client/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/client/index.ts) contains **`buildCorsairClient`**, the low-level builder that:

- Generates the runtime client object
- Attaches each plugin's methods according to its `export` type definitions
- Applies authentication and exposes the `keys` namespace for integration-level key management

This file reveals **how plugin APIs become typed methods** on the client object. If you're debugging why a plugin method isn't appearing or why auth headers aren't attaching, trace the logic here.

## Optional HTTP Server: [`packages/corsair/http.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/http.ts)

The **[`http.ts`](https://github.com/corsairdev/corsair/blob/main/http.ts)** module provides a wrapper that exposes your integration as a REST endpoint via `corsair http <port>`. It's invaluable for:

- Rapid prototyping of webhook receivers
- Debugging integrations without deploying
- Building microservices around Corsair clients

The server activates when `NODE_ENV=development` and requires a configured integration instance.

## Hub and Tunnel Orchestration: [`packages/corsair/hub.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/hub.ts)

When running in the **Corsair Hub** (hosted OAuth and webhook manager), [`packages/corsair/hub.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/hub.ts) handles:

- Hub configuration parsing
- Development connect loop (triggered by `ck_dev_…` API keys)
- Local tunnel orchestration (controlled via `CORSAIR_TUNNEL` environment variable)

Focus here if you're building OAuth flows or need the hosted tunnel for webhook development.

## Plugin Scaffolding: [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts)

The CLI utility at [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts) is your fastest path to adding new integrations. Running it:

1. Creates `packages/<name>/` with [`index.ts`](https://github.com/corsairdev/corsair/blob/main/index.ts) and test skeleton
2. Registers the plugin in [`packages/corsair/core/constants.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts)
3. Ensures correct repository layout and TypeScript configuration

Use this instead of manual setup to maintain consistency across the monorepo.

## Code Examples: From Single-Tenant to Multi-Tenant

### Single-Tenant Integration

```typescript
import { createCorsair } from 'corsair';
import { slackPlugin } from '@corsair-dev/slack';

const client = createCorsair({
  plugins: [slackPlugin],
  kek: 'my-super-secret-kek',
});

await client.slack.sendMessage({
  channel: 'C123456',
  text: 'Hello from Corsair!',
});

```

*Source: `createCorsair` in [`packages/corsair/core/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/index.ts); plugin structure from scaffolded packages.*

### Multi-Tenant with Tenant Scoping

```typescript
import { createCorsair } from 'corsair';
import { gmailPlugin } from '@corsair-dev/gmail';

const wrapper = createCorsair({
  plugins: [gmailPlugin],
  kek: 'kek-for-multi-tenant',
  multiTenancy: true,
});

const tenantClient = wrapper.withTenant('tenant-abc');
await tenantClient.gmail.listThreads();

```

*Source: `withTenant` logic in [`packages/corsair/core/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/index.ts).*

### Local HTTP Development Server

```typescript
import { http } from 'corsair';

http({ port: 3000, integration: wrapper });

```

*Source: [`packages/corsair/http.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/http.ts).*

### Scaffold a New Plugin

```bash
pnpm run generate:plugin \
  --name myplugin \
  --description "My custom integration"

```

*Source: [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts).*

## How the Core Modules Connect

1. **Factory (`createCorsair`)** receives configuration and resolves plugins
2. **Internal Config (`CorsairInternalConfig`)** stores runtime state attached via `CORSAIR_INTERNAL`
3. **Client (`buildCorsairClient`)** materializes typed plugin APIs
4. **Multi-Tenancy Wrapper (`withTenant`)** scopes clients when enabled
5. **Hub & Tunnel** provide optional hosted infrastructure for OAuth and webhooks

## Summary

- **[`packages/corsair/core/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/index.ts)** — Master this first; contains `createCorsair`, multi-tenancy, and hub integration
- **[`packages/corsair/client/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/client/index.ts)** — Second priority; reveals how plugins become typed client methods
- **[`packages/corsair/http.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/http.ts)** — Use for rapid prototyping and webhook debugging
- **[`packages/corsair/hub.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/hub.ts)** — Essential for hosted OAuth and tunnel workflows
- **[`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts)** — Always use this to scaffold new integrations consistently

## Frequently Asked Questions

### What's the fastest way to understand how Corsair initializes integrations?

Read [`packages/corsair/core/index.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/index.ts) and trace `createCorsair` from its parameter types through to the returned client or wrapper. The factory's ~200 lines contain the entire composition logic for plugins, database, keys, and tenancy.

### How does multi-tenancy actually work in Corsair?

When `multiTenancy: true` is passed to `createCorsair`, the factory returns a wrapper object with a `withTenant(tenantId)` method. Calling this method invokes `buildCorsairClient` with tenant-scoped context, ensuring isolated data per customer in SaaS deployments.

### Should I write plugins manually or use the generator?

Always use [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts). The generator ensures your plugin follows the monorepo's structural conventions, registers itself in [`packages/corsair/core/constants.ts`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/core/constants.ts), and includes the correct TypeScript boilerplate for type-safe exports.

### What's the difference between the HTTP wrapper and the Hub?

The **HTTP wrapper** ([`http.ts`](https://github.com/corsairdev/corsair/blob/main/http.ts)) is a lightweight local server for development and testing. The **Hub** ([`hub.ts`](https://github.com/corsairdev/corsair/blob/main/hub.ts)) is a production-grade hosted service handling OAuth token refresh, webhook ingress, and secure tunneling—activated when using `ck_dev_…` or production API keys.