build-integration

Build a GitBook Integration

A skill for building integrations on GitBook's developer platform: apps that run inside GitBook itself. An integration can render custom blocks in the editor, show configuration UI, listen to events (content updated, Git sync completed, space viewed), authenticate against external services with OAuth, and talk to anything over HTTP.

This skill covers the integration lifecycle — scaffold, code, develop, publish. For creating or restructuring the docs site an integration might be installed into, defer to configure-site; for authoring page content, defer to write-docs.

What an integration is (mental model)

An integration is a small TypeScript app executed by GitBook's runtime — not a script injected into pages, and not code running on the user's server. Three consequences shape everything else:

1. Rendering happens on GitBook's backend. Your component's render function runs server-side on every interaction and returns ContentKit markup (a JSX-like UI description). There is no client-side React tree you control, no DOM access, and UI updates flow through the action → new state → re-render loop.
2. You cannot inject JavaScript into a site. The site:script:inject and site:script:cookies scopes you'll see in GitBook-owned integrations are internal-only. If the user's plan amounts to "add a script tag to their docs", stop and say so early — the supported paths are custom blocks, webframes, and events.
3. Local development is a proxy, not a server you visit. gitbook dev routes the installed integration's traffic to your machine. You never open the dev server's port in a browser; you interact with the integration inside app.gitbook.com.

The project

gitbook new scaffolds this shape:

my-integration/
├── gitbook-manifest.yaml   # identity, scopes, blocks, configuration schema
├── .gitbook-dev.yaml       # local dev config (generated by `gitbook dev`)
├── package.json
└── src/
    └── index.tsx           # entry file — default-exports createIntegration()

The entry file (whatever script: in the manifest points to) default-exports createIntegration({ fetch, components, events }):

import { createIntegration, createComponent } from '@gitbook/runtime';

const helloBlock = createComponent({
    componentId: 'hello-world',            // must match a block id in the manifest
    initialState: { message: 'Say hello!' },
    action: async (element, action, context) => {
        switch (action.action) {
            case 'say':
                return { state: { message: 'Hello world' } };
            default:
                return {};
        }
    },
    render: async (element, context) => (
        <block>
            <button label={element.state.message} onPress={{ action: 'say' }} />
        </block>
    ),
});

export default createIntegration({
    components: [helloBlock],
    events: {
        space_content_updated: async (event, context) => {
            // react to content changes
        },
    },
});

A custom block only appears in the editor's insert palette (⌘ + /) if it is declared in both places: createComponent in the code and a blocks: entry in the manifest whose id matches the componentId. Forgetting one half is the most common "my block doesn't show up" cause.

The manifest, briefly

gitbook-manifest.yaml is the integration's identity and permission grant. Required: name (globally unique across all of GitBook — pick something namespaced like acme-changelog, not test), title, description, organization (org id or subdomain), visibility, scopes, and script. Request only the scopes the code actually uses — installers see them.

The manifest also declares blocks, installer-facing configurations (account-level and site-level property schemas rendered as a settings form), and secrets (e.g. CLIENT_ID: ${{ env.CLIENT_ID }}, loaded at publish time — use dotenv-cli so gitbook publish sees your .env).

Full field-by-field schema, scope list, and configuration property types: references/manifest.md. Read it whenever you're editing the manifest beyond the basics.

The development loop

The loop has a non-obvious order — publish comes before local development:

1. Prerequisites. Node 18+, a personal access token from https://app.gitbook.com/account/developer, and the CLI: npm install @gitbook/cli -g, then gitbook auth (or gitbook auth --token=<token>). If a token needs to be pasted into the conversation, export it to the environment and never echo it back or commit it.
2. Scaffold. gitbook new <dir> — prompts for name, title, organization, and scopes.
3. Publish once. gitbook publish in the project root. This registers the integration (private by default) and prints an install link.
4. Install it into at least one space or site via that link. Local dev doesn't work until it's installed somewhere.
5. Develop. gitbook dev starts the proxy: all traffic for the installed integration is served from your local code instead of the published version. Interact with it in the GitBook editor, not at the server URL. UI changes need a browser refresh; disable browser caching for a smoother loop. Logs surface in the browser console or your terminal depending on where the code runs — check both before concluding logging is broken.
6. Re-publish with gitbook publish whenever you want the hosted version updated. gitbook unpublish <name> removes it.

CLI command reference (including gitbook whoami and gitbook openapi publish): references/manifest.md.

Runtime: fetch, events, environment, OAuth

Details and full tables live in references/runtime.md — read it when writing event handlers, OAuth flows, or anything touching context.environment. The essentials:

• `fetch` handles incoming HTTP requests to the integration's public endpoint using standard Fetch API Request/Response objects. Outgoing HTTP is plain fetch too.
• `events` maps event names (installation_setup, space_installation_setup, space_view, ui_render, space_content_updated, space_visibility_updated, space_gitsync_started, space_gitsync_completed) to handlers. Some events require matching scopes.
• `context.environment` exposes apiEndpoint, apiTokens, installation info (space, status, per-installation configuration values entered by the installer), secrets, and public URLs (environment.integration.urls.publicEndpoint).
• OAuth against an external provider is a fixed pattern: a button-type configuration property whose callback_url routes to a createOAuthHandler({...}) in your fetch handler, with client id/secret coming from secrets. Don't hand-roll the redirect/token exchange.
• Calling the GitBook API from inside the integration: use context.api (an authenticated @gitbook/api client) rather than constructing your own client from raw tokens.

ContentKit: building the UI

ContentKit is the component vocabulary render can return: layout (block, vstack, hstack, divider), display (box, card, text, image, markdown), and interactive elements (button, textinput, select, switch, checkbox, radio, codeblock, webframe, modal). Interactivity model in one line: inputs bind their value to a state key; buttons dispatch actions; your action reducer returns new state; GitBook re-renders.

Read references/contentkit.md before writing any component beyond a trivial button — it has the full prop tables plus the patterns that are hard to guess: dynamic state binding for live previews, webframe postMessage communication, modals with returnValue, persisting props with @editor.node.updateProps, link unfurling via @link.unfurl + urlUnfurl manifest patterns, and markdown code-block serialization of blocks.

Publishing and sharing

Visibility in the manifest controls reach:

• private (default) — installable only by members of the owning org. Right for internal tools; stay here during development.
• unlisted — installable by any org, but only via the shared install link. Right for sharing with specific customers or beta testers.
• public — installable by anyone; required before submitting to the integration marketplace (which is a separate review process — see GitBook's "submit your app for review" docs).

Re-run gitbook publish after changing visibility. Before suggesting public, sanity-check the manifest is presentable: icon, summary (Markdown, ≤2048 chars), previewImages (1600×800), categories, externalLinks.

Working style

• Scaffold with the CLI rather than by hand when starting fresh — gitbook new wires up the manifest, TypeScript config, and @gitbook/runtime versions correctly.
• Trace a block's id chain (manifest blocks[].id ↔ componentId) whenever a component misbehaves.
• Keep secrets out of the manifest file itself — always the ${{ env.X }} indirection, never literal values.
• When the user's goal is content or site automation from outside GitBook (scripts hitting the REST API, CI pipelines), an integration may be the wrong tool — the plain API with a personal token is simpler. Integrations earn their keep when code must run inside* GitBook: blocks, config UI, event reactions, OAuth on behalf of installers.

References

• references/manifest.md — every gitbook-manifest.yaml field, all scopes, configuration property types, secrets, CLI command reference, installation/configuration flow.
• references/runtime.md — createIntegration / createComponent / createOAuthHandler signatures, event catalog, context.environment shape, HTTP in and out.
• references/contentkit.md — full component reference with props, built-in actions, and interactivity recipes (dynamic binding, webframes, modals, unfurling, markdown serialization).