tessl/npm-storybook--preview-api
Storybook's core preview API providing hooks, decorators, story composition utilities, and simulation tools for building UI components in isolation
—
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Pending
The risk profile of this skill
index.mddocs/
Storybook Preview API
Storybook Preview API is the core interface for building UI components in isolation within the Storybook preview environment. It provides React-like hooks for state management, decorators for story enhancement, CSF (Component Story Format) utilities for story composition, and simulation tools for testing scenarios.
Package Information
- Package Name: @storybook/preview-api
- Package Type: npm
- Language: TypeScript/JavaScript
- Installation:
npm install @storybook/preview-api(requires Storybook ^8.2.0)
Core Imports
For ESM:
import {
useArgs,
useGlobals,
makeDecorator,
composeStory,
StoryStore,
DocsContext,
definePreview,
experimental_useUniversalStore,
simulatePageLoad,
simulateDOMContentLoaded
} from "@storybook/preview-api";For CommonJS:
const {
useArgs,
useGlobals,
makeDecorator,
composeStory,
StoryStore,
DocsContext,
definePreview,
experimental_useUniversalStore,
simulatePageLoad,
simulateDOMContentLoaded
} = require("@storybook/preview-api");Basic Usage
import { useArgs, useGlobals, composeStory } from "@storybook/preview-api";
// Using hooks in story decorators
export const MyDecorator = (Story, context) => {
const [args, updateArgs] = useArgs();
const [globals] = useGlobals();
return <Story />;
};
// Composing portable stories
import type { Meta, StoryObj } from '@storybook/react';
import * as ButtonStories from './Button.stories';
const meta: Meta<typeof Button> = ButtonStories.default;
const Primary = composeStory(ButtonStories.Primary, meta);
// Usage in tests
test('Primary button renders correctly', () => {
render(<Primary />);
});Architecture
The Storybook Preview API is built around several key architectural components:
- Hooks System: React-like hooks providing state management and lifecycle methods for stories
- Decorator System: Powerful middleware pattern for story enhancement and composition
- CSF Engine: Component Story Format processing and normalization utilities
- Store Management: Centralized state management for stories, args, and global parameters
- Preview Environment: Web-based preview system with story selection and rendering
- Simulation Tools: Testing utilities for DOM manipulation and page lifecycle simulation
Capabilities
Hooks API
React-like hooks for state management, lifecycle methods, and communication within the Storybook preview environment. Essential for building interactive stories and custom addons.
function useArgs<TArgs>(): [TArgs, (newArgs: Partial<TArgs>) => void, (argNames?: (keyof TArgs)[]) => void];
function useGlobals(): [Args, (newGlobals: Args) => void];
function useStoryContext<TRenderer>(): StoryContext<TRenderer>;
function useParameter<S>(parameterKey: string, defaultValue?: S): S | undefined;Decorators
System for creating reusable story enhancements and middleware. Decorators wrap stories to provide additional functionality like theming, layouts, or data providers.
function makeDecorator(options: MakeDecoratorOptions): MakeDecoratorResult;
interface MakeDecoratorOptions {
name: string;
parameterName: string;
skipIfNoParametersOrOptions?: boolean;
wrapper: (storyFn: StoryFn, context: StoryContext) => any;
}Story Composition & CSF
Utilities for creating portable stories, composing story configurations, and working with Component Story Format. Perfect for testing, documentation generation, and cross-environment story usage.
function composeStory<TRenderer>(
storyAnnotations: StoryAnnotations<TRenderer, any>,
componentAnnotations: ComponentAnnotations<TRenderer, any>,
projectAnnotations?: ProjectAnnotations<TRenderer>,
defaultConfig?: ProjectAnnotations<TRenderer>,
exportsName?: string
): ComposedStoryFn<TRenderer, any>;
function composeStories<TModule>(
storiesImport: TModule,
globalConfig: ProjectAnnotations<any>,
composeStoryFn?: Function
): Record<string, ComposedStoryFn<any, any>>;Story Store & Management
Central story management system providing story loading, caching, args management, and context creation. Core infrastructure for Storybook's preview environment.
class StoryStore<TRenderer> {
storyIndex: StoryIndex;
projectAnnotations: ProjectAnnotations<TRenderer>;
userGlobals: Args;
args: ArgsStore;
hooks: HooksContext<TRenderer>;
}
function setProjectAnnotations<TRenderer>(projectAnnotations: ProjectAnnotations<TRenderer>): void;
function setDefaultProjectAnnotations<TRenderer>(defaultProjectAnnotations: ProjectAnnotations<TRenderer>): void;Preview System
Web-based preview environment with story selection, rendering, and URL-based state management. Handles the complete story rendering lifecycle in browser environments.
class PreviewWeb<TRenderer> {
constructor(args: PreviewWebArgs<TRenderer>);
ready(): Promise<void>;
render(renderOptions: RenderOptions): Promise<void>;
}
class Preview<TRenderer> {
constructor(imports: PreviewArgs<TRenderer>);
ready(): Promise<void>;
}Testing & Simulation
Tools for simulating DOM events, page lifecycle, and creating test utilities. Essential for testing stories and addons in various environments.
function simulatePageLoad(container: Element): void;
function simulateDOMContentLoaded(): void;
function createPlaywrightTest<TFixture>(baseTest: TFixture): any;Docs Context & Documentation
Context provider for documentation rendering and metadata access. Provides documentation-specific functionality for Storybook's docs pages.
class DocsContext {
constructor(channel: Channel, store: StoryStore, renderStoryToElement: Function, collectionId?: string);
componentStories(): Story[];
storyById(id?: string): Story;
getStoryContext(story: Story): StoryContext;
}Preview Configuration
Utilities for configuring the Storybook preview environment with global settings and annotations.
function definePreview(preview: ProjectAnnotations): ProjectAnnotations;Experimental Universal Store
Experimental state management system for cross-environment story state synchronization.
function experimental_useUniversalStore<T>(key: string, initialValue?: T): [T, (value: T) => void];
class experimental_UniversalStore {
get<T>(key: string): T | undefined;
set<T>(key: string, value: T): void;
subscribe<T>(key: string, listener: (value: T) => void): () => void;
}
class experimental_MockUniversalStore extends experimental_UniversalStore {
constructor(initialState?: Record<string, any>);
reset(): void;
}Types & Core Interfaces
interface Args {
[key: string]: any;
}
interface StoryContext<TRenderer = any> {
id: string;
name: string;
title: string;
parameters: Parameters;
args: Args;
argTypes: ArgTypes;
globals: Args;
hooks: HooksContext<TRenderer>;
}
interface ComposedStoryFn<TRenderer = any, TArgs = any> {
(args?: Partial<TArgs>): any;
storyName?: string;
args?: TArgs;
parameters?: Parameters;
argTypes?: ArgTypes;
}
interface ProjectAnnotations<TRenderer = any> {
parameters?: Parameters;
decorators?: DecoratorFunction<TRenderer>[];
args?: Args;
argTypes?: ArgTypes;
globals?: Args;
globalTypes?: GlobalTypes;
}
interface GlobalTypes {
[key: string]: {
name?: string;
description?: string;
defaultValue?: any;
toolbar?: {
title?: string;
icon?: string;
items?: Array<{ value: any; title: string; icon?: string }>;
showName?: boolean;
dynamicTitle?: boolean;
};
control?: {
type: 'boolean' | 'text' | 'number' | 'range' | 'object' | 'file' | 'radio' | 'inline-radio' | 'check' | 'inline-check' | 'select' | 'multi-select' | 'color' | 'date';
[key: string]: any;
};
};
}
interface ArgTypes {
[key: string]: ArgType;
}
interface ArgType {
name?: string;
description?: string;
defaultValue?: any;
type?: {
name: 'boolean' | 'string' | 'number' | 'object' | 'array' | 'function';
value?: any;
required?: boolean;
};
control?: {
type: 'boolean' | 'text' | 'number' | 'range' | 'object' | 'file' | 'radio' | 'inline-radio' | 'check' | 'inline-check' | 'select' | 'multi-select' | 'color' | 'date';
[key: string]: any;
};
table?: {
type?: { summary: string; detail?: string };
defaultValue?: { summary: string; detail?: string };
disable?: boolean;
};
}
interface Parameters {
[key: string]: any;
}
interface Channel {
emit(eventId: string, ...args: any[]): void;
on(eventId: string, listener: Function): void;
off(eventId: string, listener: Function): void;
once(eventId: string, listener: Function): void;
addListener(eventId: string, listener: Function): void;
removeListener(eventId: string, listener: Function): void;
removeAllListeners(eventId?: string): void;
}