Framework guide

Add Onboard to Next.js

Use Bootstrapware Onboard when your Next.js SaaS needs a first-run setup checklist. The widget is a Client Component. Pass the signed-in user and workspace key from your session.

This guide covers App Router. The same package works in Pages Router if you keep the component on the client and avoid putting secret keys in public env vars.

Install

pnpm add @bootstrapware/onboard

Import package CSS once for the tree that renders the checklist. Forgetting the stylesheet is the most common "it looks broken" bug.

Local adapter in a Client Component

Start local for placement and IA. No paid entitlement required. Put the widget in a file with "use client".

"use client";

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

export function SetupPanel({
  user,
  workspaceKey,
}: {
  user: { id: string; name?: string };
  workspaceKey: string;
}) {
  return (
    <Onboard
      user={user}
      workspaceKey={workspaceKey}
      items={SAAS_FIRST_RUN_ITEMS}
      adapter={createLocalAdapter({ storageKey: "app-onboard" })}
    />
  );
}

Render <SetupPanel /> from any Server or Client page. Only the checklist island needs to be a Client Component. Path A does not invent keys.

Hosted embed

For Hosted progress, omit adapter and pass flow id plus a publishable key. Use NEXT_PUBLIC_ only for publishable values. Mint authorToken in a Route Handler.

<Onboard
  flowId={process.env.NEXT_PUBLIC_ONBOARD_FLOW_ID!}
  publishableKey={process.env.NEXT_PUBLIC_BSW_ONBOARD_PUBLISHABLE_KEY!}
  user={user}
  workspaceKey={workspace.id}
  authorToken={authorTokenFromServerAction}
/>

Never put bsw_live_sec_ or bsw_test_sec_ in NEXT_PUBLIC_. Secret keys stay in Route Handlers or server-only modules. If env has no publishable key, stop and mint one at the Keys page. See API keys and environments.

BYO Route Handlers

Implement /api/onboard/progress endpoints that enforce your session, then pass adapter methods that fetch those routes. Re-bind authorship from the session. Do not trust client-supplied user.id alone. Still pass flowId + publishableKey so published config loads. Contract: adapter.

Limits worth knowing

• 32 items per flow
• 16 eligibility flags per item
• Default snooze days: 1 and 7
• Live Hosted writes need Hosted ($19.99) plus authorToken

Pitfalls specific to Next.js

• Rendering Onboard in a Server Component without "use client"
• Forgetting @bootstrapware/onboard/styles.css
• Putting a secret key in public env
• Inventing user.id instead of the session id
• Trusting client user ids on BYO routes without session checks
• Minting authorToken in a Client Component

Related: Quickstart · React guide · Cursor guide · Identity · Live demo