Digital product onboarding

.ts export interface OnboardingStep { id: string; type: 'input' | 'action' | 'review'; title: string; component: string; // Reference to registered UI component dependencies?: string[]; // IDs of steps that must be completed first guards?: string[]; // Feature flags or conditions asyncAction?: string; // Server action to trigger on completion }

export interface OnboardingConfig { flowId: string; version: number; steps: OnboardingStep[]; completionEvent: string; }

#### 2. State Machine Definition

Implement the state machine using XState. This handles transitions, context updates, and guards.

```typescript
// machine/onboarding-machine.ts
import { createMachine, assign, interpret } from 'xstate';

interface OnboardingContext {
  currentStepId: string | null;
  completedSteps: string[];
  skippedSteps: string[];
  contextData: Record<string, any>;
  error: string | null;
}

type OnboardingEvent =
  | { type: 'NEXT' }
  | { type: 'BACK' }
  | { type: 'SKIP' }
  | { type: 'COMPLETE_STEP'; stepId: string; data: any }
  | { type: 'LOAD_STATE'; context: OnboardingContext }
  | { type: 'ERROR'; message: string };

export const onboardingMachine = createMachine<OnboardingContext, OnboardingEvent>({
  id: 'onboarding',
  initial: 'loading',
  context: {
    currentStepId: null,
    completedSteps: [],
    skippedSteps: [],
    contextData: {},
    error: null,
  },
  states: {
    loading: {
      invoke: {
        src: 'fetchOnboardingState',
        onDone: {
          target: 'active',
          actions: assign({
            currentStepId: (ctx, event) => event.data.currentStepId,
            completedSteps: (ctx, event) => event.data.completedSteps,
            skippedSteps: (ctx, event) => event.data.skippedSteps,
            contextData: (ctx, event) => event.data.contextData,
          }),
        },
        onError: {
          target: 'error',
          actions: assign({ error: (_, event) => event.data.message }),
        },
      },
    },
    active: {
      on: {
        NEXT: [
          {
            target: 'completed',
            cond: 'isFlowComplete',
            actions: 'emitCompletionEvent',
          },
          {
            target: 'active',
            actions: 'advanceToNextStep',
          },
        ],
        BACK: {
          target: 'active',
          cond: 'canGoBack',
          actions: 'rewindToPreviousStep',
        },
        SKIP: {
          target: 'active',
          cond: 'isStepSkippable',
          actions: assign({
            skippedSteps: assign((ctx, event) => [...ctx.skippedSteps, ctx.currentStepId!]),
            currentStepId: (ctx) => getNextStepId(ctx),
          }),
        },
        COMPLETE_STEP: {
          target: 'active',
          actions: [
            assign({
              completedSteps: assign((ctx, event) => {
                if (!ctx.completedSteps.includes(event.stepId)) {
                  return [...ctx.completedSteps, event.stepId];
                }
                return ctx.completedSteps;
              }),
              contextData: assign((ctx, event) => ({
                ...ctx.contextData,
                [event.stepId]: event.data,
              })),
              currentStepId: (ctx) => getNextStepId(ctx),
            }),
            'persistStateToServer',
            'emitStepCompletedEvent',
          ],
        },
        ERROR: {
          target: 'error',
          actions: assign({ error: (_, event) => event.message }),
        },
      },
    },
    completed: {
      type: 'final',
      entry: 'notifyUpstream',
    },
    error: {
      on: {
        RETRY: 'loading',
      },
    },
  },
});

// Guards and Actions would be implemented based on the OnboardingConfig

3. React Integration Hook

Create a hook that wraps the machine and provides a clean API for components.

// hooks/useOnboarding.ts
import { useMachine } from '@xstate/react';
import { onboardingMachine } from '../machine/onboarding-machine';
import { useEffect, useCallback } from 'react';

export function useOnboarding(config: OnboardingConfig) {
  const [state, send] = useMachine(onboardingMachine, {
    context: {
      currentStepId: config.steps[0]?.id || null,
      completedSteps: [],
      skippedSteps: [],
      contextData: {},
      error: null,
    },
    services: {
      fetchOnboardingState: async () => {
        // Implementation: Fetch persisted state from API
        const response = await fetch('/api/onboarding/state');
        return response.json();
      },
    },
    actions: {
      persistStateToServer: async (ctx) => {
        // Implementation: Send state update to API
        await fetch('/api/onboarding/state', {
          method: 'POST',
          body: JSON.stringify(ctx),
        });
      },
      emitStepCompletedEvent: (ctx, event) => {
        // Implementation: Send analytics event
        analytics.track('onboarding_step_completed', {
          stepId: event.stepId,
          flowId: config.flowId,
        });
      },
    },
  });

  const completeStep = useCallback(
    (stepId: string, data: any) => {
      send({ type: 'COMPLETE_STEP', stepId, data });
    },
    [send]
  );

  const next = useCallback(() => send({ type: 'NEXT' }), [send]);
  const back = useCallback(() => send({ type: 'BACK' }), [send]);
  const skip = useCallback(() => send({ type: 'SKIP' }), [send]);

  return {
    state,
    context: state.context,
    completeStep,
    next,
    back,
    skip,
    isLoading: state.matches('loading'),
    isError: state.matches('error'),
    isCompleted: state.matches('completed'),
    currentStep: config.steps.find((s) => s.id === state.context.currentStepId),
  };
}

Rationale

This architecture ensures that the onboarding flow is testable, observable, and resilient. The state machine guarantees that users cannot skip required steps or bypass guards. Server-side persistence ensures that progress is never lost. The configuration schema allows product teams to iterate on the flow without engineering involvement, accelerating optimization cycles. The decoupled event system provides accurate analytics data for measuring conversion funnels.

Pitfall Guide

Production onboarding systems frequently fail due to predictable architectural errors. Avoid these pitfalls to ensure reliability and performance.

1. LocalStorage as Source of Truth

   • Mistake: Storing onboarding progress exclusively in localStorage or sessionStorage.
   • Impact: State is lost if the user clears cache, switches devices, or uses incognito mode. Recovery is impossible.
   • Best Practice: Use the server as the source of truth. Client storage may be used for optimistic UI updates, but the authoritative state must reside in the database and be synced via the state machine.

2. Missing Idempotency in Transitions

   • Mistake: Allowing the COMPLETE_STEP action to execute multiple times for the same step.
   • Impact: Duplicate side effects (e.g., creating resources twice), corrupted state, and analytics inflation.
   • Best Practice: Implement idempotency keys in API requests. The state machine should reject transitions that attempt to complete an already completed step. Use completedSteps array in context to guard against re-execution.

3. Blocking Navigation Without Recovery

   • Mistake: Implementing onboarding as a modal overlay that blocks all navigation with no way to dismiss or resume later.
   • Impact: High frustration if the user needs to access settings or documentation. If the browser crashes, the user is stuck in a broken state.
   • Best Practice: Allow navigation away from onboarding. Persist state so the user can resume. Provide a "Save and Exit" option. Use progressive disclosure for non-critical steps rather than hard blocking.

4. Ignoring Accessibility in Onboarding

   • Mistake: Building onboarding modals and overlays without ARIA attributes, focus trapping, or keyboard navigation support.
   • Impact: Exclusion of users with disabilities, legal compliance risks, and poor SEO.
   • Best Practice: Ensure all interactive elements are keyboard accessible. Use role="dialog" for modals. Trap focus within the onboarding flow. Provide clear status announcements for screen readers when steps change.

5. Analytics Bloat and Coupling

   • Mistake: Embedding analytics calls directly in UI components and firing excessive events for every micro-interaction.
   • Impact: Performance degradation due to network requests, difficult maintenance when analytics providers change, and noisy data.
   • Best Practice: Centralize analytics in the state machine middleware. Emit only meaningful business events (e.g., step_completed, flow_completed, error). Batch events where possible. Abstract the analytics provider behind an interface.

6. Hardcoding Step Logic

   • Mistake: Writing conditional logic (if step === 'profile') inside the state machine or UI components.
   • Impact: The system becomes rigid. Adding a new step or changing the order requires code changes and redeployment.
   • Best Practice: Move all step definitions, ordering, and conditions to the configuration schema. The state machine should be generic and driven entirely by the config. Use dynamic component loading based on component references in the config.

7. Security Gaps During Onboarding

   • Mistake: Relaxing security checks during onboarding or failing to validate inputs on the server.
   • Impact: Vulnerability to CSRF, injection attacks, and data corruption. Attackers may exploit onboarding endpoints to create malformed accounts.
   • Best Practice: Enforce strict input validation on the server for all onboarding actions. Implement CSRF tokens. Rate-limit onboarding endpoints. Ensure that partial data cannot be used to access protected resources until the flow is fully completed.

Production Bundle

Action Checklist

• Audit Current Flow: Map all existing onboarding steps, dependencies, and edge cases. Identify state desynchronization issues.
• Define Configuration Schema: Create a JSON schema for onboarding steps, including types, guards, and async actions.
• Implement State Machine: Build the state machine using XState or equivalent. Define all states, transitions, and guards.
• Set Up Persistence Layer: Implement server-side storage for onboarding state. Ensure atomic updates and conflict resolution.
• Integrate Analytics: Configure the state machine middleware to emit standardized events. Verify data accuracy in analytics dashboard.
• Add Error Handling: Implement retry logic for network failures. Create user-friendly error states with recovery options.
• Secure Endpoints: Apply rate limiting, CSRF protection, and input validation to all onboarding API routes.
• Test Edge Cases: Verify behavior for browser crashes, network drops, rapid clicks, and multi-device usage.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Simple Linear Flow (< 5 steps)	Config-Driven State Machine	Provides structure, persistence, and analytics with minimal overhead.	Low
Complex Flow with Branching	Hierarchical State Machine	Handles nested states and parallel regions effectively.	Medium
Highly Personalized Onboarding	AI-Adaptive Engine + State Machine	Uses ML to select steps based on user profile; state machine manages execution.	High
Legacy System Migration	Strangler Fig Pattern	Wrap existing UI with state machine layer; gradually replace components.	Medium
Mobile-First Product	Native State Machine + Local Persistence	Optimizes for offline capability and native navigation patterns.	Medium

Configuration Template

Copy this JSON structure to define your onboarding flow. Validate against your schema before deployment.

{
  "flowId": "user_onboarding_v2",
  "version": 1,
  "steps": [
    {
      "id": "welcome",
      "type": "action",
      "title": "Welcome",
      "component": "OnboardingWelcome",
      "skippable": false
    },
    {
      "id": "profile_setup",
      "type": "input",
      "title": "Profile Setup",
      "component": "ProfileForm",
      "dependencies": ["welcome"],
      "asyncAction": "updateUserProfile",
      "skippable": true
    },
    {
      "id": "preferences",
      "type": "input",
      "title": "Preferences",
      "component": "PreferencesForm",
      "dependencies": ["profile_setup"],
      "guards": ["feature:advanced_prefs"],
      "skippable": true
    },
    {
      "id": "review",
      "type": "review",
      "title": "Review",
      "component": "ReviewSummary",
      "dependencies": ["profile_setup", "preferences"],
      "skippable": false
    }
  ],
  "completionEvent": "onboarding_completed",
  "timeoutMinutes": 30
}

Quick Start Guide

1. Install Dependencies:

   npm install xstate @xstate/react
   

2. Define Configuration: Create onboarding-config.json using the template above. Customize steps for your product.
3. Initialize Machine: Import onboardingMachine and pass the configuration to the useOnboarding hook in your root onboarding component.
4. Render Steps: Use the currentStep from the hook to dynamically render the appropriate component. Map completeStep, next, back, and skip to UI controls.
5. Deploy and Monitor: Deploy the implementation. Verify analytics events in your dashboard. Monitor error rates and completion times. Iterate on configuration to optimize flow.