0
# Storybook Addon Onboarding
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @storybook/addon-onboarding
7
- **Package Type**: npm
8
- **Language**: TypeScript/React
9
- **Installation**: `npm install @storybook/addon-onboarding`
10

11
## Core Imports
12

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

15
```typescript
16
// Main package (empty export - no functional API)
17
import onboarding from "@storybook/addon-onboarding";
18
// Result: {} (empty object)
19

20
// Import public constants and types
21
import { 
22
  STORYBOOK_ADDON_ONBOARDING_CHANNEL,
23
  STORYBOOK_ADDON_ONBOARDING_STEPS 
24
} from "@storybook/addon-onboarding/constants";
25

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

30
For Storybook configuration:
31

32
```javascript
33
// .storybook/main.js
34
export default {
35
  addons: ["@storybook/addon-onboarding"]
36
};
37
```
38

39
## Basic Usage
40

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

43
```javascript
44
// .storybook/main.js
45
export default {
46
  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"],
47
  addons: [
48
    "@storybook/addon-onboarding"
49
  ]
50
};
51
```
52

53
The onboarding experience will automatically trigger when:
54
1. Navigating to `?path=/onboarding` or `?onboarding=true`
55
2. Example Button stories are present (`example-button--primary`)
56
3. Screen width is at least 730px
57

58
To manually trigger the onboarding:
59
```
60
http://localhost:6006/?path=/onboarding
61
```
62

63
## Architecture
64

65
The addon is built around several key components:
66

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

73
## Capabilities
74

75
### Addon Registration
76

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

79
```typescript { .api }
80
// Automatic registration - no manual API calls needed
81
// Registration happens in manager.tsx when:
82
// - onboarding query parameter is present OR path is '/onboarding'
83
// - example button stories are present
84
// - screen width >= 730px
85
```
86

87
### Main Package Export
88

89
Empty default export - functionality is provided through addon registration.
90

91
```typescript { .api }
92
export default {};
93
```
94

95
### Server Channel Configuration
96

97
Configures server-side telemetry and survey data collection.
98

99
```typescript { .api }
100
/**
101
 * Configures server-side channel for telemetry collection
102
 * @param channel - Storybook communication channel
103
 * @param options - Storybook options with core configuration
104
 * @returns Promise resolving to the configured channel
105
 */
106
export const experimental_serverChannel: (
107
  channel: Channel, 
108
  options: Options
109
) => Promise<Channel>;
110
```
111

112
### Preset Configuration
113

114
Legacy preset configuration for manager entry points.
115

116
```javascript { .api }
117
/**
118
 * Adds manager entry to Storybook configuration
119
 * @param entry - Existing entries array (default: [])
120
 * @returns Array with added manager entry
121
 */
122
function managerEntries(entry?: any[]): any[];
123
```
124

125
### Public Constants
126

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

129
```typescript { .api }
130
/**
131
 * Channel identifier for addon communication and telemetry
132
 */
133
export const STORYBOOK_ADDON_ONBOARDING_CHANNEL: string;
134

135
/**
136
 * Readonly array of onboarding step identifiers in sequence
137
 */
138
export const STORYBOOK_ADDON_ONBOARDING_STEPS: readonly [
139
  "1:Intro",
140
  "2:Controls", 
141
  "3:SaveFromControls",
142
  "4:CreateStory",
143
  "5:StoryCreated",
144
  "6:IntentSurvey",
145
  "7:FinishedOnboarding"
146
];
147
```
148

149
### Public Types
150

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

153
```typescript { .api }
154
/**
155
 * Type representing valid onboarding step identifiers
156
 */
157
export type StepKey = (typeof STORYBOOK_ADDON_ONBOARDING_STEPS)[number];
158

159
/**
160
 * Interface defining the structure of an onboarding step
161
 */
162
export interface StepDefinition {
163
  key: StepKey;
164
  hideNextButton?: boolean;
165
  target?: string;
166
  content: React.ReactNode;
167
  placement?: 'top' | 'bottom' | 'left' | 'right' | 'center';
168
  hideBackButton?: boolean;
169
  styles?: {
170
    tooltip?: React.CSSProperties;
171
    tooltipContent?: React.CSSProperties;
172
    tooltipTitle?: React.CSSProperties;
173
    tooltipFooter?: React.CSSProperties;
174
    buttonNext?: React.CSSProperties;
175
    buttonBack?: React.CSSProperties;
176
    buttonSkip?: React.CSSProperties;
177
  };
178
}
179
```
180

181
## Type Definitions for Server Channel API
182

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

185
```typescript { .api }
186
/**
187
 * Event structure for telemetry and survey data
188
 */
189
interface Event {
190
  type: 'telemetry' | 'survey';
191
  step: string;
192
  payload?: any;
193
}
194

195
/**
196
 * Storybook communication channel interface
197
 * Imported from 'storybook/internal/channels'
198
 */
199
interface Channel {
200
  on(eventName: string, handler: (data: any) => void): () => void;
201
  emit(eventName: string, data: any): void;
202
  off(eventName: string, handler?: (data: any) => void): void;
203
}
204

205
/**
206
 * Storybook configuration options interface
207
 * Imported from 'storybook/internal/types'
208
 */
209
interface Options {
210
  presets: {
211
    apply<T>(name: string, defaultValue: T): Promise<T>;
212
  };
213
}
214

215
/**
216
 * Core configuration interface for telemetry settings
217
 * Imported from 'storybook/internal/types'
218
 */
219
interface CoreConfig {
220
  disableTelemetry?: boolean;
221
}
222
```
223

224
## Activation Conditions
225

226
The addon has smart activation logic and only loads when:
227

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

233
When these conditions aren't met, the addon will:
234
- Log a warning message suggesting removal if Button stories are missing
235
- Silently skip loading if screen is too narrow or onboarding parameter is false
236

237
## Removal
238

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

241
1. **Remove the dependency**:
242
```bash
243
npm uninstall @storybook/addon-onboarding
244
```
245

246
2. **Remove from Storybook configuration**:
247
```javascript
248
// .storybook/main.js
249
export default {
250
  addons: [
251
    // Remove this line:
252
    // "@storybook/addon-onboarding"
253
  ]
254
};
255
```
256

257
## Telemetry and Analytics
258

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

261
- **Step Progression**: Tracks which steps users complete
262
- **Survey Responses**: Collects user intent and feedback data
263
- **Completion Analytics**: Measures onboarding success rates
264

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

267
```javascript
268
// .storybook/main.js
269
export default {
270
  core: {
271
    disableTelemetry: true
272
  }
273
};
274
```
275

276
## Dependencies
277

278
The addon requires these peer dependencies:
279
- `storybook` (workspace version)
280
- Modern browser with React support
281

282
Internal dependencies include:
283
- `react` and `react-dom` for UI components
284
- `react-joyride` for guided tour functionality
285
- `@neoconfetti/react` for celebration animations
286
- `@storybook/icons` for consistent iconography