CtrlK
BlogDocsLog inGet started
Tessl Logo

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
Overview
Eval results
Files

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;

Hooks API

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;
}

Decorators

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 Composition

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;

Story Store

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>;
}

Preview System

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;

Testing & Simulation

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;
}

Install with Tessl CLI

npx tessl i tessl/npm-storybook--preview-api
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@storybook/preview-api@8.6.x
Publish Source
CLI
Badge
tessl/npm-storybook--preview-api badge