@bootstrapware/onboard
v0.1.2
Published
Embeddable first-run setup checklist for SaaS. BYO progress or Bootstrapware Hosted.
Maintainers
Readme
@bootstrapware/onboard
Embeddable first-run setup checklist for small production SaaS: required and optional steps, dependencies, eligibility, facts, dismiss, and snooze.
The first incomplete unblocked item is highlighted as the next step. Items with href use a primary Continue (or ctaLabel) link and Mark complete as secondary; items without href keep Mark complete primary. Clicking the href CTA does not auto-complete. The widget ignores javascript:, other non-http(s) schemes, and protocol-relative hrefs, including tab, newline, and backslash forms browsers still parse as those URLs.
Presentation
presentation is "section" (default, inline on the page), "modal" (dialog and backdrop), "window" (floating panel, page stays usable), or "launcher" (corner button). Modal, window, and launcher start closed unless defaultOpen. Escape, the backdrop, or Hide closes modal and launcher. Escape or Hide closes a window.
Undo and the celebrate card
Skipped optional steps show Undo and Mark complete. Undo deletes that skipped progress row. It does not clear a complete row. When every required step is done, the checklist shows a celebrate card: You're all set and Required setup is complete. The progress bar stays.
onStepAction(stepId, action) reports complete, skip, unskip, open, and copy. A non-blank codeSnippet on a step renders as a copyable code block. ref.uncompleteStep(stepId) clears a complete row when the adapter implements it.
Local / demo is free. BYO is $9.99 / month (you store progress). Hosted is $19.99 / month (Bootstrapware stores progress). Bootstrapware does not authenticate end users. Your app asserts user.id.
pnpm add @bootstrapware/onboardPeer dependencies: react and react-dom (>= 18).
Local / demo
import { Onboard, createLocalAdapter } from "@bootstrapware/onboard";
import "@bootstrapware/onboard/styles.css";
<Onboard
user={{ id: session.user.id, name: session.user.name }}
workspaceKey={workspace.id}
adapter={createLocalAdapter({ storageKey: "demo-onboard" })}
items={[
{ key: "create_workspace", title: "Create your workspace", progressScope: "workspace" },
{ key: "invite_teammate", title: "Invite a teammate", dependsOn: ["create_workspace"], progressScope: "workspace" },
]}
/>Hosted
Publishable keys may appear in the browser. Secret keys must stay server-side. Call ensure_test_publishable for a test publishable key. Never mint live or secret keys via MCP.
<Onboard
flowId="flw_..."
publishableKey="bsw_live_pub_..."
user={currentUser}
workspaceKey={workspace.id}
authorToken={authorTokenFromBff}
/>Optional apiBaseUrl defaults to https://onboard.bootstrapware.co.
BYO ($9.99): pass an OnboardAdapter. Progress stays on your backend. See the packaged AGENTS.md.
Theme
Optional theme="light" or theme="dark". Omit theme and the checklist stays the light cream default. v1 does not follow prefers-color-scheme or the system theme.
Set these CSS custom properties on the embed root: --bsw-ob-bg, --bsw-ob-panel, --bsw-ob-fg, --bsw-ob-muted, --bsw-ob-line, --bsw-ob-ok, --bsw-ob-error, --bsw-ob-accent, --bsw-ob-accent-fg, --bsw-ob-radius. Those overrides are the supported API. Do not fight .bsw-* classes. With theme="dark", target .bsw-ob[data-theme="dark"].
Security
- Do not put
bsw_live_sec_orbsw_test_sec_in client code. - Host-asserted
user.idcan be forged if a publishable key leaks. Mitigate with origins andrequireAuthorTokenplus a secret-mintedauthorToken. - Never send host context or flags through MCP. MCP configures flows only.
Docs
- Product: https://bootstrapware.co/onboard
- Demo: https://bootstrapware.co/onboard/demo
- Quickstart: https://bootstrapware.co/onboard/docs/quickstart
- Agent rules (
AGENTS.md): https://bootstrapware.co/onboard/docs/agents - Identity /
authorToken: https://bootstrapware.co/onboard/docs/identity
For coding agents, copy the packaged AGENTS.md into your repo rules, or point the agent at the docs URL above.
License
MIT
