build-integration

GitBook インテグレーションを構築する

GitBook の開発者プラットフォーム上でインテグレーションを構築するためのスキルです。GitBook 内で動作するアプリを作成できます。インテグレーションでは、エディターにカスタムブロックを表示したり、設定 UI を表示したり、イベント（コンテンツの更新、Git 同期の完了、スペースの表示）をリッスンしたり、OAuth で外部サービスに対して認証したり、HTTP 経由であらゆるものと通信したりできます。

このスキルでは、インテグレーションのライフサイクル（スキャフォールド、コーディング、開発、公開）を扱います。インテグレーションをインストールする サイト の作成や再構成については configure-site を、ページコンテンツの作成については write-docs を参照してください。

インテグレーションとは（基本的な考え方）

インテグレーションは、GitBook のランタイムで実行される小さな TypeScript アプリです。ページに挿入されるスクリプトでも、ユーザーのサーバーで実行されるコードでもありません。ここから、あらゆる要素を形作る3つの重要な点が導かれます。

1. レンダリングは GitBook のバックエンドで行われます。 コンポーネントの render 関数は、インタラクションのたびにサーバーサイドで実行され、ContentKit マークアップ（JSX に似た UI の記述）を返します。自分で制御できるクライアントサイドの React ツリーや DOM アクセスはなく、UI の更新はアクション → 新しい状態 → 再レンダリングのループを通じて行われます。
2. サイトに JavaScript を挿入することはできません。 GitBook が所有するインテグレーションで見かける site:script:inject と site:script:cookies のスコープは、内部専用です。ユーザーの計画が「ドキュメントに script タグを追加する」ことであれば、その時点で作業を止め、早めにその旨を伝えてください。サポートされている方法は、カスタムブロック、ウェブフレーム、イベントです。
3. ローカル開発では、アクセスするサーバーではなくプロキシを使います。 gitbook dev は、インストール済みの インテグレーションのトラフィックを開発マシンにルーティングします。開発サーバーのポートをブラウザーで開くことはありません。app.gitbook.com 内でインテグレーションを操作します。

プロジェクト

gitbook new は、次の構成をスキャフォールドします。

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()

エントリーファイル（マニフェストの script: が指すファイル）は、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
        },
    },
});

カスタムブロックがエディターの挿入パレット（⌘ + /）に表示されるのは、両方 の場所で宣言されている場合のみです。つまり、コード内の createComponent と、id が componentId に一致するマニフェスト内の blocks: エントリーの両方が必要です。片方を忘れることが、「ブロックが表示されない」という最もよくある原因です。

マニフェストの概要

gitbook-manifest.yaml は、インテグレーションの識別情報と権限の付与を定義します。必須項目は、name（GitBook 全体で一意。test ではなく、acme-changelog のように名前空間を含めてください）、title、description、organization（組織 ID またはサブドメイン）、visibility、scopes、script です。コードで実際に使用するスコープだけを要求してください。インストールするユーザーに表示されます。

マニフェストでは、blocks、インストールするユーザー向けの configurations（設定フォームとして表示される、アカウントレベルおよびサイトレベルのプロパティスキーマ）、secrets（例：CLIENT_ID: ${{ env.CLIENT_ID }}。公開時に読み込まれます。gitbook publish から .env が参照されるよう、dotenv-cli を使用してください）も宣言します。

全フィールドのスキーマ、スコープ一覧、設定プロパティの型については、references/manifest.md を参照してください。基本事項を超えてマニフェストを編集する際は、必ず確認してください。

開発ループ

このループには分かりにくい順序があります。ローカル開発より先に公開します。

1. 前提条件。 Node 18 以降、https://app.gitbook.com/account/developer で取得した個人アクセストークン、そして CLI が必要です。npm install @gitbook/cli -g を実行し、その後 gitbook auth（または gitbook auth --token=<token>）を実行してください。トークンを会話に貼り付ける必要がある場合は、環境変数に設定し、エコーバックしたりコミットしたりしないでください。
2. スキャフォールド。 gitbook new <dir> を実行します。名前、タイトル、組織、スコープの入力を求められます。
3. 一度公開します。 プロジェクトのルートで gitbook publish を実行します。これによりインテグレーションが登録され（デフォルトでは非公開）、インストールリンクが表示されます。
4. そのリンクを使って、少なくとも1つのスペースまたはサイトにインストールします。どこかにインストールするまではローカル開発できません。
5. 開発します。 gitbook dev を実行するとプロキシが起動します。インストール済みインテグレーションへのすべてのトラフィックは、公開済みのバージョンではなく、ローカルコードから提供されます。サーバー URL ではなく、GitBook エディターで操作してください。UI の変更を反映するにはブラウザーを更新する必要があります。スムーズに開発するには、ブラウザーのキャッシュを無効にしてください。コードの実行場所に応じて、ログはブラウザーのコンソールまたはターミナルに表示されます。ログが機能していないと判断する前に、両方を確認してください。
6. ホスト版を更新するときは、gitbook publish で再公開します。gitbook unpublish <name> で削除できます。

CLI コマンドのリファレンス（gitbook whoami や gitbook openapi publish を含む）：references/manifest.md。

ランタイム：fetch、イベント、環境、OAuth

詳細とすべての表は references/runtime.md にあります。イベントハンドラー、OAuth フロー、または context.environment に関わる処理を書く場合は、こちらをお読みください。要点は次のとおりです。

• fetch は、標準の Fetch API の Request／Response オブジェクトを使って、インテグレーションの公開エンドポイントへの受信 HTTP リクエストを処理します。送信 HTTP も通常の fetch を使います。
• events はイベント名（installation_setup、space_installation_setup、space_view、ui_render、space_content_updated、space_visibility_updated、space_gitsync_started、space_gitsync_completed）をハンドラーに対応付けます。一部のイベントには、対応するスコープが必要です。
• context.environment では、apiEndpoint、apiTokens、インストール情報（スペース、ステータス、インストーラーが入力したインストールごとの configuration 値）、secrets、および公開 URL（environment.integration.urls.publicEndpoint）を参照できます。
• OAuth を外部プロバイダーに対して行う場合は、決められたパターンを使います。button 型の設定プロパティの callback_url から、fetch ハンドラー内の createOAuthHandler({...}) にルーティングし、クライアント ID／シークレットは secrets から取得します。リダイレクトやトークン交換を独自に実装しないでください。
• インテグレーション内から GitBook API を呼び出す場合：生のトークンから独自のクライアントを構築するのではなく、context.api（認証済みの @gitbook/api クライアント）を使ってください。

ContentKit：UI の構築

ContentKit は、render が返すことのできるコンポーネントの語彙です。レイアウト（block、vstack、hstack、divider）、表示（box、card、text、image、markdown）、インタラクティブ要素（button、textinput、select、switch、checkbox、radio、codeblock、webframe、modal）があります。インタラクションモデルを一文で説明すると、入力は値を state キーにバインドし、ボタンはアクションをディスパッチし、action リデューサーは新しい状態を返し、GitBook が再レンダリングします。

単純なボタンを超えるコンポーネントを書く前に、references/contentkit.md をお読みください。すべてのプロパティの表に加えて、推測しにくいパターンも説明しています。ライブプレビューのための動的な状態のバインド、webframe の postMessage 通信、returnValue を使ったモーダル、@editor.node.updateProps によるプロパティの永続化、@link.unfurl と urlUnfurl マニフェストパターンによるリンクの展開、ブロックの Markdown コードブロックへのシリアライズなどです。

公開と共有

マニフェストの公開範囲によって、利用できる範囲が決まります。

• private（デフォルト）— 所有する組織のメンバーのみインストールできます。内部ツールに適しており、開発中はこの設定にします。
• unlisted — どの組織でもインストールできますが、共有されたインストールリンクからのみ利用できます。特定の顧客やベータテスターとの共有に適しています。
• public — 誰でもインストールできます。インテグレーションマーケットプレイスへの申請前に必要です（審査プロセスは別途行われます。GitBook の「アプリを審査に申請する」ドキュメントを参照してください）。

公開範囲を変更した後は、gitbook publish を再実行してください。public を提案する前に、マニフェストが公開に適した状態か確認してください。icon、summary（Markdown、2048 文字以下）、previewImages（1600×800）、categories、externalLinks が必要です。

作業スタイル

• 新しく始めるときは、手作業ではなく CLI でひな形を作成してください。gitbook new を実行すると、マニフェスト、TypeScript 設定、@gitbook/runtime のバージョンが適切に設定されます。
• コンポーネントが正しく動作しない場合は、ブロックの ID の連鎖をたどってください（マニフェストの blocks[].id ↔ componentId）。
• マニフェストファイル自体にシークレットを含めないでください。必ず ${{ env.X }} を介して参照し、値を直接記述しないでください。
• ユーザーの目的が GitBook の外部からのコンテンツ操作やサイト自動化（REST API を呼び出すスクリプト、CI パイプラインなど）の場合、インテグレーションは適切なツールではない可能性があります。個人用トークンを使う通常の API のほうが簡単です。コードを GitBook 内で実行する必要がある場合、つまりブロック、設定 UI、イベントへの反応、インストーラーに代わる OAuth には、インテグレーションが役立ちます。

参考資料

• references/manifest.md — gitbook-manifest.yaml の全フィールド、すべてのスコープ、設定プロパティの型、シークレット、CLI コマンドのリファレンス、インストール／設定フロー。
• references/runtime.md — createIntegration／createComponent／createOAuthHandler のシグネチャ、イベントカタログ、context.environment の構造、HTTP の送受信。
• references/contentkit.md — プロパティ、組み込みアクション、インタラクティブ機能のレシピ（動的バインディング、ウェブフレーム、モーダル、アンファール、Markdown のシリアライズ）を含む、コンポーネントの完全なリファレンス。