Recipe

Onboarding agent

Walk every new user through setup in under 90 seconds — no docs, no confusion, no churn.

The problem

New users land on your dashboard and freeze. They don't know where to click first. Support tickets pile up asking the same three questions. Activation rate sits at 40% because the product feels hostile to newcomers.

What you'll build

A lightweight onboarding agent that detects first-login state, greets the user by name, and guides them through exactly four steps: connect account, install helper, run first scan, read the report. Each step waits for real completion before advancing.

Walkthrough

  1. 1

    Detect first-login

    Set a boolean flag in your user record. On next page load, if the flag is false and the session is fresh, inject the agent overlay. Clear the flag after step four completes.

  2. 2

    Greet and anchor

    Render a small toast anchored bottom-right. Use the user's first name. One sentence: what Nimbus does and why they'll love it. Single CTA button: “Set up in 90s”.

  3. 3

    Step-by-step flow

    Expand the toast into a modal card. Show a progress bar (0/4 → 4/4). Each step has a title, one-line instruction, and a disabled button that enables only when the backend confirms the action. Poll every 2 seconds.

  4. 4

    Celebrate and dismiss

    On step four completion, swap the progress bar for a checkmark. Show a one-line celebration. Auto-dismiss after 5 seconds. Set the first-login flag to true so the agent never appears again.

Tech notes

  • Keep the agent as a single client component mounted in your root layout. No global state library needed — a context provider with useReducer is plenty.
  • Polling endpoint: GET /api/onboarding/status. Returns { step: number, done: boolean }.
  • Completion endpoint: POST /api/onboarding/complete. Sets the flag server-side.
  • Tailwind animation for the toast entrance: animate-slide-up with a custom keyframe in tailwind.config.ts.
Back to docs