Framework guide

Onboard for React

Install @bootstrapware/onboard, import styles, render <Onboard /> in a client boundary with user, workspaceKey, and an adapter or Hosted props. Bootstrapware does not authenticate end users.

Install

pnpm add @bootstrapware/onboard

Import @bootstrapware/onboard/styles.css once near the feature.

Path A — local

import { Onboard, createLocalAdapter, SAAS_FIRST_RUN_ITEMS } from "@bootstrapware/onboard";
import "@bootstrapware/onboard/styles.css";

<Onboard
  user={{ id: session.user.id, name: session.user.name }}
  workspaceKey={workspace.id}
  context={{ role: membership.role, plan: workspace.plan }}
  facts={{ hasBilling: billingConnected }}
  items={SAAS_FIRST_RUN_ITEMS}
  adapter={createLocalAdapter({ storageKey: "app-onboard" })}
/>

Call completeStep from your app on real actions and pass facts so the widget reconciles on mount. No keys required.

Path B — Hosted

<Onboard
  flowId="flw_..."
  publishableKey={process.env.NEXT_PUBLIC_BSW_ONBOARD_PUBLISHABLE_KEY}
  user={currentUser}
  workspaceKey={workspace.id}
  authorToken={authorTokenFromBff}
/>

Live Hosted needs Hosted ($19.99) and a BFF-minted token. Test keys work unpaid. See modes.

Path C — BYO

Pass a full OnboardAdapter and still pass flowId + publishableKey so published config loads. Progress stays on your API. Use onEvent for Slack or CRM; Bootstrapware webhooks are Hosted-only.

Pitfalls

• Inventing user.id
• Forgetting styles.css
• Putting secret keys in the client
• Sending host context through MCP
• Omitting workspaceKey so shared steps never complete for teammates

Related: React component · Embed checklist · Next.js · Identity · Demo