Framework guide

First-run setup checklist for Vite + React

Vite apps usually separate a React SPA from a backend API. Onboard fits that shape: the widget runs in the browser; your API owns BYO progress (or Hosted stores it). Onboard does not authenticate end users. Assert user.id from your session.

Install

pnpm add @bootstrapware/onboard

// main.tsx or SetupPage.tsx
import "@bootstrapware/onboard/styles.css";

Local / demo in the SPA

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

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

Use your normal SPA auth: cookie credentials, bearer token, or whatever your API already expects. The checklist does not manage login for you.

Hosted keys with Vite env

Prefix browser-exposed vars with VITE_. Only publishable keys belong there.

#.env.local
VITE_API_URL=http://localhost:3001
VITE_ONBOARD_FLOW_ID=flw_...
VITE_BSW_PUBLISHABLE_KEY=bsw_test_pub_...

<Onboard
  flowId={import.meta.env.VITE_ONBOARD_FLOW_ID}
  publishableKey={import.meta.env.VITE_BSW_PUBLISHABLE_KEY}
  user={currentUser}
  workspaceKey={workspace.id}
  authorToken={authorTokenFromBff}
/>

Mint authorToken on your API, never in the Vite bundle. Register your SPA origin for CORS when the browser calls Onboard Hosted APIs. See origins. Your own API still needs CORS (or a same-origin proxy) for BYO adapter fetches.

BYO against your API

Pass an OnboardAdapter that fetches your API (for example VITE_API_URL + "/onboard/progress") with the session token. Honor pinned revision and dual generations on the server.

Mode resolution

adapter prop (progress) → Hosted progress when no adapter and flowId + publishableKey → local
Published config loads whenever flowId + publishableKey are set.

Pitfalls

• Forgetting styles.css
• Using a non-VITE_ prefix and wondering why env is undefined in the browser
• Exposing secret keys as VITE_ vars
• CORS blocking either your API or the Hosted config / progress fetch
• Skipping host-asserted user.id
• Minting authorToken in the browser

Related: React guide · API keys · Modes · Origins · Live demo