Storybook Addon Onboarding

Storybook Addon Onboarding provides an interactive guided tour for new Storybook users, helping them learn how to write stories and understand Storybook's core features. The addon automatically triggers when users visit the onboarding path and example Button stories are present, displaying a React-based tutorial interface.

Package Information

• Package Name: @storybook/addon-onboarding
• Package Type: npm
• Language: TypeScript/React
• Installation: npm install @storybook/addon-onboarding

Core Imports

This addon primarily works through automatic registration and does not require explicit imports in user code. The main export is:

// Main package (empty export - no functional API)
import onboarding from "@storybook/addon-onboarding";
// Result: {} (empty object)

// Import public constants and types
import { 
  STORYBOOK_ADDON_ONBOARDING_CHANNEL,
  STORYBOOK_ADDON_ONBOARDING_STEPS 
} from "@storybook/addon-onboarding/constants";

// Import types (TypeScript only)
import type { StepKey, StepDefinition } from "@storybook/addon-onboarding/Onboarding";

For Storybook configuration:

// .storybook/main.js
export default {
  addons: ["@storybook/addon-onboarding"]
};

Basic Usage

The addon is designed to work automatically without manual code integration. Simply add it to your Storybook configuration:

// .storybook/main.js
export default {
  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"],
  addons: [
    "@storybook/addon-onboarding"
  ]
};

The onboarding experience will automatically trigger when:

1. Navigating to ?path=/onboarding or ?onboarding=true
2. Example Button stories are present (example-button--primary)
3. Screen width is at least 730px

To manually trigger the onboarding:

http://localhost:6006/?path=/onboarding

Architecture

The addon is built around several key components:

• Automatic Registration: Self-registers with Storybook's manager API when conditions are met
• Conditional Loading: Only loads when appropriate conditions are met (URL parameters, example stories, screen width)
• React Components: Uses modern React patterns including lazy loading and Suspense for optimal performance
• Telemetry Integration: Tracks user progress and collects analytics data for improvement
• State Management: Manages onboarding flow state through a guided step-by-step experience

Capabilities

Addon Registration

The addon automatically registers itself with the Storybook manager when appropriate conditions are met.

// Automatic registration - no manual API calls needed
// Registration happens in manager.tsx when:
// - onboarding query parameter is present OR path is '/onboarding'
// - example button stories are present
// - screen width >= 730px

Main Package Export

Empty default export - functionality is provided through addon registration.

export default {};

Server Channel Configuration

Configures server-side telemetry and survey data collection.

/**
 * Configures server-side channel for telemetry collection
 * @param channel - Storybook communication channel
 * @param options - Storybook options with core configuration
 * @returns Promise resolving to the configured channel
 */
export const experimental_serverChannel: (
  channel: Channel, 
  options: Options
) => Promise<Channel>;

Preset Configuration

Legacy preset configuration for manager entry points.

/**
 * Adds manager entry to Storybook configuration
 * @param entry - Existing entries array (default: [])
 * @returns Array with added manager entry
 */
function managerEntries(entry?: any[]): any[];

Public Constants

The addon exports several constants that can be used by other addons or advanced integrations.

/**
 * Channel identifier for addon communication and telemetry
 */
export const STORYBOOK_ADDON_ONBOARDING_CHANNEL: string;

/**
 * Readonly array of onboarding step identifiers in sequence
 */
export const STORYBOOK_ADDON_ONBOARDING_STEPS: readonly [
  "1:Intro",
  "2:Controls", 
  "3:SaveFromControls",
  "4:CreateStory",
  "5:StoryCreated",
  "6:IntentSurvey",
  "7:FinishedOnboarding"
];

Public Types

The addon exports TypeScript types for advanced integrations and other addons.

/**
 * Type representing valid onboarding step identifiers
 */
export type StepKey = (typeof STORYBOOK_ADDON_ONBOARDING_STEPS)[number];

/**
 * Interface defining the structure of an onboarding step
 */
export interface StepDefinition {
  key: StepKey;
  hideNextButton?: boolean;
  target?: string;
  content: React.ReactNode;
  placement?: 'top' | 'bottom' | 'left' | 'right' | 'center';
  hideBackButton?: boolean;
  styles?: {
    tooltip?: React.CSSProperties;
    tooltipContent?: React.CSSProperties;
    tooltipTitle?: React.CSSProperties;
    tooltipFooter?: React.CSSProperties;
    buttonNext?: React.CSSProperties;
    buttonBack?: React.CSSProperties;
    buttonSkip?: React.CSSProperties;
  };
}

Type Definitions for Server Channel API

These types are imported from Storybook's internal APIs and used in the server channel configuration.

/**
 * Event structure for telemetry and survey data
 */
interface Event {
  type: 'telemetry' | 'survey';
  step: string;
  payload?: any;
}

/**
 * Storybook communication channel interface
 * Imported from 'storybook/internal/channels'
 */
interface Channel {
  on(eventName: string, handler: (data: any) => void): () => void;
  emit(eventName: string, data: any): void;
  off(eventName: string, handler?: (data: any) => void): void;
}

/**
 * Storybook configuration options interface
 * Imported from 'storybook/internal/types'
 */
interface Options {
  presets: {
    apply<T>(name: string, defaultValue: T): Promise<T>;
  };
}

/**
 * Core configuration interface for telemetry settings
 * Imported from 'storybook/internal/types'
 */
interface CoreConfig {
  disableTelemetry?: boolean;
}

Activation Conditions

The addon has smart activation logic and only loads when:

1. URL Conditions: Path equals /onboarding OR query parameter onboarding=true
2. Story Presence: Example Button stories exist (example-button--primary)
3. Screen Width: Minimum 730px width for proper UI display
4. Telemetry: Not disabled in Storybook core configuration

When these conditions aren't met, the addon will:

• Log a warning message suggesting removal if Button stories are missing
• Silently skip loading if screen is too narrow or onboarding parameter is false

Removal

This addon is designed as a one-time educational experience. Once users complete the onboarding, they can remove it:

1. Remove the dependency:

npm uninstall @storybook/addon-onboarding

1. Remove from Storybook configuration:

// .storybook/main.js
export default {
  addons: [
    // Remove this line:
    // "@storybook/addon-onboarding"
  ]
};

Telemetry and Analytics

The addon collects anonymous usage data to improve the onboarding experience:

• Step Progression: Tracks which steps users complete
• Survey Responses: Collects user intent and feedback data
• Completion Analytics: Measures onboarding success rates

All telemetry can be disabled through Storybook's core configuration:

// .storybook/main.js
export default {
  core: {
    disableTelemetry: true
  }
};

Dependencies

The addon requires these peer dependencies:

• storybook (workspace version)
• Modern browser with React support

Internal dependencies include:

• react and react-dom for UI components
• react-joyride for guided tour functionality
• @neoconfetti/react for celebration animations
• @storybook/icons for consistent iconography