Integration runtime

GitBook Runtime is the platform that lets you build and run integrations within GitBook. Integrations can extend GitBook’s functionality by providing custom UI components, handling events, managing OAuth authentication, and communicating over HTTP. This guide explains how to build an integration, what each key element does, and how they interact.

The main building blocks are:

• Integration Initialization – Register your integration.

• UI Components – Create custom, interactive components.

• OAuth Handling – Manage authentication flows.

• Environment Context – Access runtime and installation details.

• HTTP Communication – Fetch external data using HTTP.

• Actions & Rendering – Define component behavior and display.

• Event Handling – Listen and respond to GitBook events.

• URL Utilities – Work with URLs and query strings.

createIntegration

Integrations are created using the createIntegration() method. This method is the entrypoint for your integration and sets up its runtime context, including HTTP fetch methods, UI components, and event handlers.

export default createIntegration({
  fetch: async (request, context) => {
    // Process an HTTP request.
    return new Response(JSON.stringify({ message: "Hello World" }), {
      headers: { "Content-Type": "application/json" }
    });
  },
  components: [
    // A named component created using createComponent().
    myComponent
  ],
  events: {
    space_view: async (event, context) => {
      console.log("Space viewed:", event);
    },
  },
});

createIntegration() accepts the following object parameters:

Key	Type	Description
fetch	Async Function	A function to handle incoming HTTP requests or action dispatches.
components	Array	A list of UI component definitions created using createComponent().
events	Object	An object mapping event names to their handler functions.

createComponent

UI components let you build interactive elements that appear in GitBook’s quick insert menu (⌘ + /) or in the configuration screen of your integration. Use the createComponent() method to define a component’s identifier, initial state, actions, and rendering logic.

const myComponent = createComponent({
  componentId: "unique-id",
  initialState: (props) => ({ message: "Click me" }),
  action: async (element, action, context) => {
    switch (action.action) {
      case "say":
        return { state: { message: "Hello World" } };
      default:
        return {};
    }
  },
  render: async (element, context) => {
    return (
      <block>
        <button label={element.state.message} onPress={{ action: "say" }} />
      </block>
    );
  },
});

createComponent() accepts the following object parameters:

Key	Type	Description
componentId	string	Unique identifier for the component.
initialState	Function (props) ⇒ object	Function that initializes the component state based on its props.
action	Async Function	Callback that handles user interactions; receives element, action, and context.
render	Async Function	Function that returns the component’s UI as ContentKit markup.

createOAuthHandler

When your integration requires user authentication via OAuth, you use createOAuthHandler() to define the OAuth flow. This function sets up redirection, token exchange, and extraction of credentials.

const oauthHandler = createOAuthHandler({
  redirectURL: `${environment.integration.urls.publicEndpoint}/oauth`,
  clientId: environment.secrets.CLIENT_ID,
  clientSecret: environment.secrets.CLIENT_SECRET,
  authorizeURL: "https://linear.app/oauth/authorize",
  accessTokenURL: "https://api.linear.app/oauth/token",
  extractCredentials: (response) => {
    if (!response.ok) {
      throw new Error(`Failed to exchange code for access token ${JSON.stringify(response)}`);
    }
    return {
      configuration: {
        oauth_credentials: { access_token: response.access_token },
      },
    };
  },
});

createOAuthHandler() accepts the following object parameters:

Parameter	Type	Description	Example Value
clientId*	string	Your client application ID from the OAuth provider.	"my-client-id"
clientSecret*	string	Your client secret from the OAuth provider.	"my-client-secret"
authorizeURL*	string	The URL where users are redirected for authorization.	"https://oauth.example.com/authorize"
accessTokenURL*	string	The URL used to exchange the authorization code for an access token.	"https://oauth.example.com/token"
redirectURL	string	(Optional) URL used for redirection if a static URL is needed.	"https://myapp.example.com/oauth"
scopes	string[]	An array of scopes to request during authentication.	["read", "write"]
prompt	string	(Optional) Configuration for prompting the user during authentication.	"consent"
extractCredentials	function	A function that processes the OAuth response and returns credentials in the expected format.	(response) => { … }

Rendering components

The render function returns the UI for the component using ContentKit markup.

render: async (element, context) => {
  return (
    <block>
      <button label={element.state.message} onPress={{ action: "say" }} />
    </block>
  );
},

Environment context

GitBook provides an environment object that gives your integration details about the runtime context, such as API endpoints, integration configuration, installation details, and secrets.

// Accessing environment values in your fetch or render method:
const { apiEndpoint, integration, secrets } = context.environment;
console.log("API endpoint:", apiEndpoint);

The context.environment object can include the following:

API information

Key	Type	Description
apiEndpoint	string	URL of the HTTP API.
apiTokens	object	Contains authentication tokens for the API.

Integration information

Key	Type	Description
integration	object	Details about the integration itself.

Site installation (if applicable)

Key	Type	Description
space	string	ID of the space where the integration is installed.
status	object	Installation status; e.g., Active, Pending, Paused.
configuration	object	Custom configuration variables for the space.
externalIds	any	External identifiers.
urls	object	Contains URLs associated with the installation (e.g., public endpoint).

Organization installation (if applicable)

Key	Type	Description
id	string	Installation ID.
space_selection	object	Specifies whether all spaces or selected spaces are used.
configuration	object	Custom configuration for the organization.
urls	object	Contains organization-related URLs.
externalIds	string[]	Array of external IDs assigned by the integration.
target	string	Target of the integration installation.

Runtime secrets

Key	Type	Description
secrets	object	Secrets stored on the integration for runtime use. Defined in the integration's configuration.

Events

GitBook fires events when specific actions occur (like viewing a page or updating content). Your integration can listen to these events to update state, log information, or trigger other actions.

Depending on the event, your integration may need the correct scope permissions.

Inside the createIntegration() call, you define event handlers:

export default createIntegration({
  events: {
    space_view: async (event, context) => {
      console.log("Space viewed event:", event);
    },
  },
});

Here are the available events you can read:

Event Name	Description
installation_setup	Triggered when the integration is first installed globally.
space_installation_setup	Triggered when the integration is installed into a specific space.
space_view	Triggered when a user views a space.
ui_render	Triggered when the integration's UI component is rendered.
space_content_updated	Triggered when content in the space is changed or updated.
space_visibility_updated	Triggered when a space's visibility settings are changed.
space_gitsync_started	Triggered when a Git sync process begins for a space.
space_gitsync_completed	Triggered when a Git sync process completes for a space.

Actions

Interactive components can respond to user events via actions. They are defined in your component when using createComponent().

action: async (element, action, context) => {
  // Process the action
  switch (action.action) {
    case "say":
      return { state: { message: "Hello World" } };
    default:
      return {};
  }
},

HTTP communication

Integrations communicate with external services via HTTP using the Fetch API.

Option	Type	Description	Example Value
method	string	HTTP method (GET, POST, etc.).	"POST"
headers	object	HTTP headers as key/value pairs.	{ "Content-Type": "application/json" }
body	string	Payload to send with the request.	'{"message": "Hello World"}'

Fetch Method Example

fetch: async (request, context) => {
  const data = { message: "Hello World" };
  return new Response(JSON.stringify(data), {
    headers: {
      "Content-Type": "application/json",
    },
  });
}

Request Example:

const request = new Request("https://example.com", {
  method: "POST",
  body: '{"message": "Hello World"}',
});

Response Example:

const handleFetchEvent = async (request, context) => {
  return new Response(JSON.stringify({ message: "Hello World" }), {
    headers: { "Content-Type": "application/json" }
  });
};

Learn more from the MDN Request docs and MDN Response docs.