@bpinternal/integration-hub

React UI components and optional Botpress runtime hooks for building integration hub experiences.

Two ways to use this package

UI only (@bpinternal/integration-hub)

You provide your own data and wire your own API calls. The package gives you layout components, cards, grids, filters, and setup wizard shells. Use this when you have a non-Botpress backend or want full control over data fetching.

Required peers: react, react-dom, framer-motion, @base-ui/react, clsx, tailwind-merge, lucide-react

UI + Botpress runtime (@bpinternal/integration-hub/runtime)

You pass a @botpress/client instance and the package handles fetching integrations, mapping data to UI types, and executing install/uninstall/enable/disable mutations. Use this when your app already talks to the Botpress API.

Additional peers: @botpress/client, @tanstack/react-query

@botpress/client and @tanstack/react-query are marked as optional peer dependencies. They are only needed when importing from ./runtime. UI-only consumers do not need to install them.

Quick start

Install

pnpm add @bpinternal/integration-hub react react-dom framer-motion @base-ui/react clsx tailwind-merge lucide-react

If using the Botpress runtime:

pnpm add @botpress/client @tanstack/react-query

@bpinternal/integration-hub/runtime includes a built-in configuration form renderer backed by @bpinternal/static-zui-form.

If your app does not already provide Radix-style design tokens, import the package fallback theme:

import '@bpinternal/integration-hub/theme.css'

Option A: Drop-in screen (fastest)

A single component that handles everything — fetching, mapping, catalog, detail views, mutations.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { BotpressIntegrationHub } from '@bpinternal/integration-hub/runtime'

const queryClient = new QueryClient()

export const IntegrationsPage = ({ client, workspaceId, botId }) => (
  <QueryClientProvider client={queryClient}>
    <BotpressIntegrationHub
      client={client}
      workspaceId={workspaceId}
      botId={botId}
      onInstall={(integration) => toast.success(`${integration.title} installed`)}
      onUninstall={(integration) => toast.success(`${integration.title} removed`)}
      onError={(error) => toast.error(error.message)}
    />
  </QueryClientProvider>
)

By default, BotpressIntegrationHub renders integration configuration fields using Static ZUI Form. Pass renderConfigurationForm only if you want to override this default behavior.

Option B: Hooks + UI components (more control)

Use the hooks for data/mutations but compose your own layout with the package's UI components.

import { useIntegrationHub, useIntegrationDetails } from '@bpinternal/integration-hub/runtime'
import {
  IntegrationHubBody,
  IntegrationGridCard,
  IntegrationInstalledList,
  IntegrationDetailsLayout,
  IntegrationCapabilitiesCards
} from '@bpinternal/integration-hub'

export const IntegrationsPage = ({ client, workspaceId, botId }) => {
  const [selectedId, setSelectedId] = useState(null)
  const [search, setSearch] = useState('')

  const hub = useIntegrationHub({ client, workspaceId, botId })
  const details = useIntegrationDetails({ client, workspaceId, botId, integrationId: selectedId })

  return (
    <IntegrationHubBody
      view="hub"
      searchInput={search}
      onSearchInputChange={setSearch}
      hubIntegrations={hub.integrations}
      sidebarIntegrations={hub.integrations}
      installedIntegrations={hub.installedIntegrations}
      isHubLoading={hub.isLoading}
      renderIntegrationCard={(integration) => (
        <IntegrationGridCard
          name={integration.title ?? integration.name}
          iconUrl={integration.iconUrl}
          installed={integration.installed}
          onClick={() => setSelectedId(integration.id)}
        />
      )}
      renderInstalledIntegrations={({ integrations, searchTerm, categoryOrder }) => (
        <IntegrationInstalledList
          integrations={integrations}
          searchTerm={searchTerm}
          categoryOrder={categoryOrder}
          onSelectIntegration={(i) => setSelectedId(i.id)}
        />
      )}
      renderIntegrationDetails={() => (
        <IntegrationDetailsLayout
          title={details.definition?.title ?? ''}
          iconUrl={details.definition?.iconUrl}
          onBack={() => setSelectedId(null)}
          onInstall={() => hub.install(selectedId)}
          isInstalled={Boolean(details.installedState)}
          isInstalling={hub.isInstalling}
        >
          <IntegrationCapabilitiesCards
            actionCards={details.capabilities.actionCards}
            eventCards={details.capabilities.eventCards}
          />
        </IntegrationDetailsLayout>
      )}
    />
  )
}

Option C: Mappers only (bring your own data layer)

Pure functions that convert @botpress/client types to the package's UI types. No React, no hooks. Use these if you already have your own React Query setup and just want to stop duplicating mapping logic.

import {
  toHubItem,
  toCapabilityCards,
  toConnectionMethods,
  getInstalledIntegrations,
  filterAndSortIntegrations
} from '@bpinternal/integration-hub/runtime'

// In your own React Query hook:
const integrations = await client.listPublicIntegrations({ version: 'latest' })
const bot = await client.getBot({ id: botId })

const installed = getInstalledIntegrations(bot.integrations)
const installedByName = new Map(installed.map((i) => [i.name, i]))

const hubItems = integrations.map((summary) => toHubItem({ summary, installedByName }))
const filtered = filterAndSortIntegrations({ integrations: hubItems, searchTerm: 'slack' })

Option D: UI only (no Botpress client)

Use the components with any data source. You handle all fetching and pass data as props.

import { IntegrationHubBody, IntegrationGridCard } from '@bpinternal/integration-hub'

const myIntegrations = [
  { id: '1', name: 'slack', title: 'Slack', description: 'Chat with Slack', iconUrl: '...' }
]

export const MyHub = () => (
  <IntegrationHubBody
    view="hub"
    searchInput={search}
    onSearchInputChange={setSearch}
    hubIntegrations={myIntegrations}
    sidebarIntegrations={myIntegrations}
    installedIntegrations={[]}
    renderIntegrationCard={(integration) => (
      <IntegrationGridCard name={integration.title} iconUrl={integration.iconUrl} />
    )}
    renderInstalledIntegrations={() => <div>No installed integrations</div>}
    renderIntegrationDetails={(id) => <div>Details for {id}</div>}
  />
)

API reference

useIntegrationHub(options)

Hook that fetches the integration catalog and bot state, and provides mutation functions.

Options:

Returns:

useIntegrationDetails(options)

Hook that fetches a single integration's full definition, bot-installed state, and capabilities.

Options:

Returns:

BotpressIntegrationHub (composed screen)

Drop-in component that wires useIntegrationHub + useIntegrationDetails + all UI components. Manages view/search/selection/tab state internally.

Required props: client, workspaceId, botId

Optional overrides:

Render slots (for things the package cannot own):

Callbacks:

Mapper functions

Pure functions (no React) exported from @bpinternal/integration-hub/runtime:

What this package does NOT include

These are the consumer's responsibility:

Customizing defaults

The package ships with generic defaults. Override them for your product:

• bannerSlides — promotional banner content (pass your own slides or an empty array to hide)
• categories — integration categories with icons (defaults to 13 common categories)
• filterMenuLabels — deep-merge with defaults to change labels like { verification: { official: 'Made by Botpress' } }
• noResultsDocumentationLink — link shown when search has no results
• formatGithubLabel on IntegrationSetupMetadataBar — custom GitHub URL display formatting
• categoryResolver — function to override how integrations are assigned to categories

UI components

All exported from @bpinternal/integration-hub:

Styling requirements

1. Import package CSS

The package ships precompiled component styles in theme.css. Import it once in your app entrypoint:

import '@bpinternal/integration-hub/theme.css'

You do not need to add @bpinternal/integration-hub to Tailwind content globs for runtime styles. Tailwind scanning of package source is only useful when developing against unpublished local source.

2. CSS custom properties

Components use Radix-style color tokens. Either use @radix-ui/themes or define these variables:

:root {
  --gray-1: #ffffff;
  --gray-2: #f8f9fa;
  --gray-3: #f1f3f5;
  --gray-5: #e1e5ea;
  --gray-6: #d0d7de;
  --gray-7: #bfc8d3;
  --gray-8: #9aa4b2;
  --gray-9: #7a8594;
  --gray-10: #6b7280;
  --gray-11: #4b5563;
  --gray-12: #111827;

  --gray-a2: rgba(17, 24, 39, 0.04);
  --gray-a3: rgba(17, 24, 39, 0.07);
  --gray-a4: rgba(17, 24, 39, 0.1);
  --gray-a5: rgba(17, 24, 39, 0.14);
  --gray-a6: rgba(17, 24, 39, 0.2);
  --gray-a8: rgba(17, 24, 39, 0.4);

  --blue-a2: rgba(37, 99, 235, 0.12);
  --blue-8: #3b82f6;
  --blue-11: #1d4ed8;

  --grass-3: #ecfdf3;
  --grass-5: #a7f3d0;
  --grass-10: #16a34a;

  --accent-9: #0ea5e9;
  --accent-11: #0284c7;
}

3. Container queries

IntegrationHubBody uses native CSS container queries for responsive grids. If you rebuild package styles from source in a Tailwind v3 app, add:

import containerQueries from '@tailwindcss/container-queries'
export default { plugins: [containerQueries] }

Build

pnpm --filter @bpinternal/integration-hub build
pnpm --filter @bpinternal/integration-hub type-check

Publish

pnpm --filter @bpinternal/integration-hub exec npm version patch
pnpm --filter @bpinternal/integration-hub exec npm publish --access public

prepack runs clean && build automatically before publish.

Note: Depending on options passed to the botpress client (x-multiple-integrations = true), the integrations from Botpress Cloud are keyed by their ALIAS, not their ID. For edits that intend to use the integration ID, make sure to explicitly use the .id parameter.