> Documentation index: https://docs.beetl.io/llms.txt

# Build integrations

> What a Connect package is, and how it reaches a tenant.

Source: https://docs.beetl.io/connect/
Last updated: 2026-11-10

When Beetl has no integration for a system you use, you can write one. An integration is a
**Connect package**: a small TypeScript project written against the
[`@beetlio/connect`](https://github.com/beetlio/connect) SDK. The SDK is open source under the
Apache-2.0 license, so you can read its source and type definitions, run its examples, and open
issues on GitHub.

- [SDK source on GitHub](https://github.com/beetlio/connect): Source code, examples and issues for `@beetlio/connect`.

- [SDK user guide](https://beetlio.github.io/connect/): The SDK's own guide to configuration, authentication, pagination and checkpoints.

## What a package describes

A package describes one system. Its `integration.ts` file default-exports a single
`defineIntegration(...)` call with three parts:

| Part       | What it declares                                                                                         |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| Metadata   | A key, a display name, a description and an optional icon.                                               |
| Connection | Where the API lives, how to authenticate, the settings a user fills in, and an optional connection test. |
| Syncs      | One entry per stream of records, each with a record schema, and optionally settings and a checkpoint.    |

The SDK derives a manifest from that definition, and Beetl builds the app's forms from it: the
settings and credential fields on a new connection, and the syncs a user can add. Once a package is
installed, that contract is fixed. A package does not choose how records are written. The person
who adds a sync chooses Append or Replace in the app. For how these objects fit together in a
tenant, see [Connection types, connections and syncs](https://docs.beetl.io/concepts/connections-and-integrations).

Packages built with an SDK older than 0.5 are not supported and must be rebuilt. See
[Rebuilding older packages](https://docs.beetl.io/connect/distribution#rebuilding-older-packages).

## From code to a running sync

    ### Write and test locally [#write-and-test-locally]

    Write `integration.ts`, then use the `beetl-connect` CLI to run a sync on your machine and inspect
    the records it produces. See [Local development](https://docs.beetl.io/connect/local-development) and
    [Authoring a sync](https://docs.beetl.io/connect/authoring-a-source).

    ### Pack [#pack]

    `beetl-connect pack` turns the project into a `.tgz` source package.

    ### Upload [#upload]

    A TenantAdmin uploads the package under Settings → Tenant → Custom connection types. Beetl builds
    it and adds it as a connection type. See [Pack and upload](https://docs.beetl.io/connect/distribution).

    ### Connect and sync [#connect-and-sync]

    Anyone in the tenant can create a connection from the new type and add syncs. See
    [Integrations](https://docs.beetl.io/sources/integrations).

## In this section

### Guides

| Page                                                            | What it covers                                                                                                     |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [Local development](https://docs.beetl.io/connect/local-development)                 | Installing the SDK, running a sync on your machine with the beetl-connect CLI, and packing.                        |
| [Authoring a sync](https://docs.beetl.io/connect/authoring-a-source)                 | One complete package: settings, credentials, a record schema, checkpoints, logging and errors.                     |
| [Authentication](https://docs.beetl.io/connect/oauth-and-rest)                       | Declaring credentials or OAuth, how tokens are refreshed, and how requests paginate, retry and handle rate limits. |
| [Pack and upload](https://docs.beetl.io/connect/distribution)                        | Packing a package, uploading it to a tenant, reading the build result, and removing a connection type.             |
| [Building with a coding agent](https://docs.beetl.io/connect/building-with-an-agent) | The workflow for writing an integration with a coding agent.                                                       |

### Reference

| Page                                                 | What it covers                                                                                                                                                                       |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Write modes](https://docs.beetl.io/connect/write-modes)                  | Append and Replace, chosen for each sync when it is set up: what each does to the sync's dataset, how they work with checkpoints and partitioning, and the limits each run must fit. |
| [The contract rule](https://docs.beetl.io/connect/schema-change-contract) | What is fixed once a connection type is installed, and how to ship a change as a new connection type.                                                                                |
| [The sandbox](https://docs.beetl.io/connect/sandbox)                      | Where package code runs, what it can reach, the limits it has to fit in, and how failures look.                                                                                      |
| [SDK reference](https://docs.beetl.io/connect/sdk-reference)              | The public API of `@beetlio/connect` 0.6: exports, the integration definition, the sync context, auth helpers and CLI commands.                                                      |