0
# Storybook
1

2
Storybook is a comprehensive frontend workshop for building, documenting, and testing UI components in isolation across multiple frameworks including React, Vue, Angular, Svelte, and Web Components. It provides a complete development environment with CLI tools, development server, visual testing capabilities, and an extensive addon ecosystem for enhanced functionality.
3

4
## Package Information
5

6
- **Package Name**: storybook
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install storybook`
10

11
## Core Imports
12

13
The Storybook package provides multiple import paths for different functionalities:
14

15
```typescript
16
// Core functionality
17
import { composeStory, composeStories } from "storybook/preview-api";
18
import { action, actions } from "storybook/actions";
19
import { expect, userEvent } from "storybook/test";
20
import { create, themes } from "storybook/theming";
21

22
// Manager API (experimental)
23
import { useStorybookApi } from "storybook/manager-api";
24

25
// Internal APIs (advanced usage)
26
import { styled, css } from "storybook/internal/theming";
27
import { Button, Modal } from "storybook/internal/components";
28
import { logger } from "storybook/internal/client-logger";
29
```
30

31
For CommonJS:
32
```javascript
33
const { composeStory, composeStories } = require("storybook/preview-api");
34
const { action, actions } = require("storybook/actions");
35
const { expect, userEvent } = require("storybook/test");
36
const { create, themes } = require("storybook/theming");
37
```
38

39
## Basic Usage
40

41
```typescript
42
import { composeStory, setProjectAnnotations } from "storybook/preview-api";
43
import { action } from "storybook/actions";
44
import { expect, userEvent, within } from "storybook/test";
45

46
// Set up project-level configuration
47
setProjectAnnotations({
48
  parameters: {
49
    backgrounds: { default: 'light' }
50
  }
51
});
52

53
// Compose a story for testing
54
const ComposedButton = composeStory(ButtonStory, ButtonMeta);
55

56
// Use in tests
57
test('button handles click', async () => {
58
  const handleClick = action('clicked');
59
  render(<ComposedButton onClick={handleClick} />);
60
  
61
  const button = screen.getByRole('button');
62
  await userEvent.click(button);
63
  
64
  expect(handleClick).toHaveBeenCalledOnce();
65
});
66
```
67

68
## Architecture
69

70
Storybook is built around several key architectural components:
71

72
- **CLI Tools**: Command-line interface for project initialization, development, and build operations
73
- **Preview API**: Core story composition and execution engine for running stories outside Storybook
74
- **Manager API**: Experimental state management system for Storybook manager UI
75
- **Actions System**: Event tracking and logging for component interactions
76
- **Testing Integration**: Built-in testing utilities with instrumentation and mocking
77
- **Theming Engine**: Complete UI theming system based on Emotion CSS-in-JS
78
- **Framework Support**: Multiple framework packages (React, Vue, Angular, etc.) with corresponding builders
79
- **Addon Ecosystem**: Extensible plugin system for custom functionality
80
- **Internal APIs**: Advanced APIs for building addons and custom integrations
81

82
## Capabilities
83

84
### CLI Commands and Development Tools
85

86
Command-line interface for project initialization, development server, build operations, and project management. Essential for setting up and managing Storybook projects.
87

88
```typescript { .api }
89
// Primary CLI commands (via storybook binary)
90
storybook dev [options]     // Start development server
91
storybook build [options]   // Build static Storybook
92
storybook init [options]    // Initialize Storybook in project
93
storybook add <addon>       // Add an addon
94
storybook remove <addon>    // Remove an addon  
95
storybook upgrade          // Upgrade Storybook packages
96
storybook info             // Environment debugging info
97
storybook migrate          // Run migration scripts
98
storybook sandbox          // Create sandbox templates
99
```
100

101
[CLI Commands and Tools](./cli-commands.md)
102

103
### Story Composition and Testing
104

105
Core functionality for composing and testing stories outside of the Storybook environment. Essential for unit testing, integration testing, and component validation workflows.
106

107
```typescript { .api }
108
function composeStory<TRenderer, TArgs>(
109
  story: Story<TRenderer, TArgs>,
110
  meta: Meta<TRenderer, TArgs>,
111
  projectAnnotations?: ProjectAnnotations<TRenderer>
112
): ComposedStory<TRenderer, TArgs>;
113

114
function composeStories<TModule extends StoriesModule>(
115
  module: TModule,
116
  projectAnnotations?: ProjectAnnotations<TRenderer>
117
): ComposedStoryModule<TModule>;
118

119
function setProjectAnnotations<TRenderer>(
120
  annotations: ProjectAnnotations<TRenderer>
121
): void;
122
```
123

124
[Story Composition](./story-composition.md)
125

126
### Action Tracking
127

128
Action tracking system for logging and monitoring component interactions and events. Provides automatic event capture and manual action creation with configurable options.
129

130
```typescript { .api }
131
function action(name: string, options?: ActionOptions): HandlerFunction;
132

133
function actions<T extends string>(...handlers: T[]): ActionsMap<T>;
134
function actions<T extends string>(
135
  handlerMap: Record<T, string>,
136
  options?: ActionOptions
137
): ActionsMap<T>;
138

139
interface ActionOptions {
140
  depth?: number;
141
  clearOnStoryChange?: boolean;
142
  limit?: number;
143
  implicit?: boolean;
144
  id?: string;
145
}
146
```
147

148
[Actions and Event Tracking](./actions.md)
149

150
### Testing Utilities
151

152
Comprehensive testing utilities built on top of popular testing libraries with Storybook-specific instrumentation and integrations.
153

154
```typescript { .api }
155
const expect: Expect;
156
const userEvent: UserEvent;
157

158
interface MockUtilities {
159
  mock(path: string | Promise<unknown>, factory?: ModuleMockOptions): void;
160
}
161
const sb: MockUtilities;
162
```
163

164
[Testing and Mocking](./testing.md)
165

166
### Theming and Styling
167

168
Complete theming system for customizing Storybook's UI appearance with pre-built themes and custom theme creation capabilities.
169

170
```typescript { .api }
171
function create(vars?: ThemeVarsPartial, rest?: object): ThemeVars;
172

173
const themes: {
174
  light: ThemeVars;
175
  dark: ThemeVars;
176
  normal: ThemeVars;
177
};
178

179
interface ThemeVars {
180
  base: 'light' | 'dark';
181
  colorPrimary: string;
182
  colorSecondary: string;
183
  appBg: string;
184
  appContentBg: string;
185
  appPreviewBg: string;
186
  // ... extensive theming properties
187
}
188
```
189

190
[Theming and Customization](./theming.md)
191

192
### Component Highlighting
193

194
Visual highlighting system for emphasizing specific DOM elements within stories, useful for documentation and interactive tutorials.
195

196
```typescript { .api }
197
const HIGHLIGHT = 'storybook/highlight';
198
const REMOVE_HIGHLIGHT = 'storybook/remove-highlight';
199
const RESET_HIGHLIGHT = 'storybook/reset-highlight';
200
const SCROLL_INTO_VIEW = 'storybook/scroll-into-view';
201

202
interface HighlightOptions {
203
  elements: string[] | HTMLElement[];
204
  color?: string;
205
  style?: 'solid' | 'dashed' | 'dotted';
206
}
207
```
208

209
[Element Highlighting](./highlighting.md)
210

211
### Viewport Management
212

213
Viewport control system for testing components across different screen sizes and device configurations.
214

215
```typescript { .api }
216
interface Viewport {
217
  name: string;
218
  styles: ViewportStyles;
219
  type?: 'desktop' | 'mobile' | 'tablet' | 'other';
220
}
221

222
interface ViewportStyles {
223
  height: string;
224
  width: string;
225
}
226

227
type ViewportMap = Record<string, Viewport>;
228
```
229

230
[Viewport Control](./viewport.md)
231

232
### Manager API and State Management
233

234
Experimental API for Storybook manager-side state management and UI customization. Provides access to stories, addons, and global state.
235

236
```typescript { .api }
237
function useStorybookApi(): API;
238
function useStorybookState(): State;
239
function useChannel(): Channel;
240

241
interface API {
242
  selectStory: (storyId: string) => void;
243
  getCurrentStoryData: () => Story | undefined;
244
  setOptions: (options: Options) => void;
245
  addPanel: (id: string, panel: Panel) => void;
246
}
247
```
248

249
[Manager API](./manager-api.md)
250

251
### Framework Support
252

253
Framework-specific packages providing deep integration with popular frontend frameworks and their build tools.
254

255
```typescript { .api }
256
// Framework packages
257
import type { Meta, StoryObj } from "@storybook/react";
258
import type { Meta, StoryObj } from "@storybook/vue3";
259
import type { Meta, StoryObj } from "@storybook/angular";
260
import type { Meta, StoryObj } from "@storybook/svelte";
261

262
// Builder packages
263
import { viteFinal } from "@storybook/builder-vite";
264
import { webpackFinal } from "@storybook/builder-webpack5";
265
```
266

267
[Framework Integration](./framework-support.md)
268

269
### Internal APIs and Components
270

271
Advanced APIs and UI components for building custom addons and extending Storybook functionality. These are internal APIs that may change between versions.
272

273
```typescript { .api }
274
// Internal theming (Emotion-based)
275
import { styled, css, keyframes, ThemeProvider } from "storybook/internal/theming";
276

277
// UI Components
278
import { Button, Modal, Tabs, Toolbar } from "storybook/internal/components";
279

280
// Core utilities
281
import { logger } from "storybook/internal/client-logger";
282
import { Channel } from "storybook/internal/channels";
283

284
// CSF tools
285
import { loadCsf, writeCsf } from "storybook/internal/csf-tools";
286
```
287

288
**Note**: Internal APIs are subject to change and should be used with caution. They are primarily intended for addon development and advanced customization scenarios.
289

290
## Core Types
291

292
```typescript { .api }
293
interface Story<TRenderer = unknown, TArgs = unknown> {
294
  (args: TArgs, context: StoryContext<TRenderer>): unknown;
295
  storyName?: string;
296
  parameters?: Parameters;
297
  args?: Partial<TArgs>;
298
  argTypes?: ArgTypes<TArgs>;
299
  decorators?: DecoratorFunction<TRenderer, TArgs>[];
300
}
301

302
interface Meta<TRenderer = unknown, TArgs = unknown> {
303
  title?: string;
304
  component?: unknown;
305
  parameters?: Parameters;
306
  args?: Partial<TArgs>;
307
  argTypes?: ArgTypes<TArgs>;
308
  decorators?: DecoratorFunction<TRenderer, TArgs>[];
309
}
310

311
interface StoryContext<TRenderer = unknown> {
312
  id: string;
313
  name: string;
314
  title: string;
315
  parameters: Parameters;
316
  args: Args;
317
  argTypes: ArgTypes;
318
  globals: Args;
319
  viewMode: ViewMode;
320
  loaded: Record<string, unknown>;
321
}
322

323
interface ComposedStory<TRenderer = unknown, TArgs = unknown> {
324
  (args?: Partial<TArgs>): unknown;
325
  id: string;
326
  storyName: string;
327
  args: TArgs;
328
  parameters: Parameters;
329
  argTypes: ArgTypes<TArgs>;
330
  play?: PlayFunction<TRenderer, TArgs>;
331
}
332

333
type ProjectAnnotations<TRenderer = unknown> = {
334
  parameters?: Parameters;
335
  decorators?: DecoratorFunction<TRenderer>[];
336
  args?: Args;
337
  argTypes?: ArgTypes;
338
  globals?: Args;
339
  globalTypes?: GlobalTypes;
340
};
341
```