Quickstart

Embed a first-run setup checklist in minutes. Free local/demo forever; BYO ($9.99) when you own progress; Hosted ($19.99) when Bootstrapware stores progress and summaries.

1. Install

pnpm add @bootstrapware/onboard

2. Choose a mode

Local / demo: createLocalAdapter (free).

BYO ($9.99): pass an OnboardAdapter plus hosted flow config for items and eligibility.

Hosted ($19.99): omit adapter; pass flowId + publishableKey.

Progress resolve order: explicit adapter → Hosted when flowId + publishable key and no adapter → local. Published config still loads whenever flowId + publishable key are set (Path C). See Modes.

3. Embed (local)

Path A needs items (or hosted config). Without them the widget shows the empty state. Use SAAS_FIRST_RUN_ITEMS or your own keys.

"use client";

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

export function SetupChecklist() {
  return (
    <Onboard
      user={{ id: session.user.id, name: session.user.name }}
      workspaceKey={workspace.id}
      items={SAAS_FIRST_RUN_ITEMS}
      adapter={createLocalAdapter({ storageKey: "demo-onboard" })}
    />
  );
}

4. Embed (Hosted)

After you create and publish a flow in the dashboard (or via secret key / MCP), pass the flow id and a publishable key. Call ensure_test_publishable for a test publishable. Live and secret keys stay dashboard-only. Never invent a key.

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

Live Hosted requires authorToken minted server-side. Test keys can write tokenless.

5. Host-complete and facts

Call completeStep from your app when users finish real actions. Pass facts for reconciliation on mount. Never send host context through MCP.

Related: Modes · Identity · Adapter · Next.js guide · Live demo