Naming, Hierarchy, and TypeScript

Purpose and Scope

This page explains how to keep a growing Storybook understandable in the sidebar and safe to maintain in TypeScript. Storybook organization has two reader-facing layers: the place where a component appears in the navigation tree, and the state name attached to each story export. TypeScript adds the author-facing layer that checks whether those named states still match the component API. The repository docs for writing stories emphasize that typed stories improve productivity, surface missing props in the editor, and allow Storybook to infer component types for generated Controls tables.

Sources: docs/writing-stories/typescript.mdx

The practical goal is to make story files serve several audiences at once. Designers and reviewers need meaningful sidebar labels; engineers need state names that describe behavior without repeating the entire component path; tests and documentation need stories whose args remain valid as components evolve. Treating naming and typing as one workflow prevents a common failure mode: a neatly organized Storybook that renders stale or misleading component states because an arg no longer exists, a required prop was omitted, or a shared play function lost type information.

Relevant Source Files

• docs/writing-stories/typescript.mdx — Documents Storybook’s built-in TypeScript support for stories, including Meta, StoryObj, generic prop typing, satisfies, custom args, and the way inferred component types support Controls.
• docs/configure/integration/typescript.mdx — Documents the TypeScript configuration surface for Storybook projects, including main.ts, zero-configuration setup, built-in types for APIs, addons, and stories, plus framework-specific TypeScript options.

Sidebar Naming and Hierarchy

Storybook’s naming model should be planned around how readers browse. The official docs describe two organization methods: implicit hierarchy, where file location determines sidebar placement, and explicit hierarchy, where a story title places the component. Use implicit hierarchy when repository folders already reflect packages, domains, or product areas that readers recognize. Use explicit hierarchy when the published Storybook needs a curated information architecture that differs from the source tree. Either way, the hierarchy should answer where a component belongs before the individual story names answer which state is being shown.

A useful convention is to make component titles broad and story exports specific. For example, the navigation path might represent a family such as Components, Forms, or Pages, while the story export names represent states such as Primary, Disabled, Loading, or WithValidationError. Avoid encoding the entire path into every story name because it makes search results noisy and generated docs harder to scan. Conversely, avoid vague story names when a component has several business states. The sidebar title establishes context; the story export should describe the visible or interactive state inside that context.

Type-Safe CSF Pattern

The TypeScript story model starts with the same two pieces that Component Story Format exposes: component metadata and named stories. Storybook’s docs call the default export the component meta, which describes and configures the component and its stories. The named exports are the stories themselves. Storybook provides utility types for both pieces: Meta for the default export and StoryObj for story exports. Typing both makes the relationship between a component, its shared configuration, and each named state visible to TypeScript rather than leaving it as an informal authoring convention.

Sources: docs/writing-stories/typescript.mdx

Meta and StoryObj are generic types, so authors can provide either the component type or a props type. That generic connection is what lets TypeScript prevent invalid args and type the arguments received by decorators, play functions, and loaders. This matters beyond editor convenience. Decorators often provide layout or application context, loaders prepare data, and play functions script interactions. If those functions receive typed story context, a renamed prop or changed arg shape is caught near the story file instead of surfacing later in the Canvas, generated docs, or interaction tests.

Sources: docs/writing-stories/typescript.mdx

A representative CSF TypeScript shape is:

import type { Meta, StoryObj } from '@storybook/your-framework';
import { Button } from './Button';
 
const meta = {
  component: Button,
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Primary: Story = {
  args: {
    label: 'Button',
  },
};

For TypeScript 4.9 and newer, the docs recommend satisfies for stricter checking. With this operator, TypeScript can report missing required args as well as invalid ones. It also helps when sharing a play function across stories because TypeScript can infer whether the play function is defined. Finally, using satisfies allows typeof meta to be passed into StoryObj, which tells TypeScript that the story type should derive its args from the typed metadata instead of from a repeated, manually maintained prop declaration.

Sources: docs/writing-stories/typescript.mdx

Configuration and Framework Integration

Story file typing is only half of the TypeScript experience. Storybook also supports TypeScript in project configuration. The integration docs describe main.ts as an ESM module written in TypeScript, giving projects baseline framework configuration while enabling stricter type checking and editor autocompletion. That means the same safety model applies to the configuration that discovers stories, registers addons, selects the framework integration, and applies integration-specific options. A typed configuration file helps teams avoid drift between how stories are authored and how Storybook is actually built and run.

Sources: docs/configure/integration/typescript.mdx

Most projects do not need additional TypeScript setup because Storybook provides zero-configuration support and built-in types for APIs, addons, and stories. When customization is needed, the configuration docs distinguish framework behavior. For several Webpack-based non-React renderers, options such as check, checkOptions, and skipCompiler control type checking and compiler parsing. For React, Storybook relies on react-docgen by default to process TypeScript files, infer component metadata, and generate types automatically for improved performance and type safety. These options affect the metadata that powers docs and controls.

Sources: docs/configure/integration/typescript.mdx

Compact Reference

Edge Cases and Authoring Checklist

There are a few important constraints to remember. The TypeScript docs note that additional satisfies-based safety is not available in the same way for Angular and Web Components because those renderers rely on class and decorator metadata that exists at runtime but does not fully expose required property information at compile time. For those projects, typed stories are still useful, but authors should be more deliberate when checking required inputs, docs output, and Controls behavior. Framework-specific inference limits should influence review practices, especially for shared design-system components.

Sources: docs/writing-stories/typescript.mdx

When adding a new story file, first decide whether the hierarchy should follow folders or an explicit title. Next, name story exports after user-visible states rather than implementation details. Then type the meta and story exports with Meta, StoryObj, and satisfies where supported. Finally, verify that generated Controls show the expected props and that any decorators, loaders, or play functions receive typed context. If metadata or type checking behaves unexpectedly, inspect the project’s main.ts TypeScript configuration before changing the story pattern itself.

Sources: docs/writing-stories/typescript.mdx, docs/configure/integration/typescript.mdx

Next Steps

Read the Component Story Format page next if you need the full structure of default exports, named story exports, and portable story conventions. Read Args and Arg Types when you want to understand how typed args become editable inputs and documentation tables. Read Decorators, Loaders, and Play Function when a named state needs shared context, asynchronous setup, or scripted interaction. For project-wide behavior, continue to Configure Overview so the typed story files and typed main.ts configuration are treated as one coherent Storybook authoring system.