Addons API and Integration Catalog

Purpose and Scope

This page connects two related tasks for addon maintainers and consumers: using Storybook's public addon APIs, and making an addon discoverable in the integration catalog. An addon is a package that extends Storybook with functionality outside the core experience, such as accessibility checks, controls, documentation features, links, or custom panels. The integration catalog is the public listing where teams browse addons and recipes. The catalog workflow is not a code registration step inside a Storybook project; it is a publishing and metadata workflow for npm packages that want to be indexed and presented consistently.

Storybook's public addon API is split by runtime context. The manager context is the outer Storybook application shell: navigation, panels, toolbar UI, and other manager-side surfaces. The preview context is where stories render and where an addon can configure behavior around the rendered component. The official Addons API documentation names storybook/manager-api for interacting with the manager UI and Storybook API, and storybook/preview-api for controlling or configuring addon behavior. Catalog metadata then describes the completed package so users can find it, evaluate supported frameworks, and install it correctly.

Sources: docs/addons/integration-catalog.mdx

Relevant Source Files

docs/addons/integration-catalog.mdx - Defines Storybook's catalog submission model, the distinction between addons and recipes, npm package requirements, required addon metadata, optional storybook presentation metadata, and the framework identifiers used by catalog indexing.

System-to-Code Mapping

The repository documentation defines the integration catalog as a listing for two integration types: addons and recipes. For addons, the catalog is populated by querying npm's registry for Storybook-specific metadata in each package's package.json. That means catalog eligibility depends on the package that is published to npm, not on a manual entry inside this repository. Maintainers should think of the catalog as a metadata contract layered on top of the package contract: publish a working npm addon, include the expected files, and expose enough structured information for the catalog to classify and display it.

Sources: docs/addons/integration-catalog.mdx

The source document makes the required package shape explicit. A catalog-ready addon package needs a package.json with module information and addon metadata, a README.md with installation and configuration instructions, a /dist directory containing transpiled ES5 code, and a root-level preset.js written as an ES5 module. These requirements support different consumers at once: npm provides discovery and installation, the README explains adoption, the distribution directory serves executable package code, and the preset file gives Storybook a conventional integration point for configuration.

Sources: docs/addons/integration-catalog.mdx

API Components

The Addons API is the programmatic layer used while building an addon. Use storybook/manager-api when the addon needs to contribute or interact with manager UI, and use storybook/preview-api when the addon affects preview-side behavior around rendered stories. The official docs show imports such as useStorybookApi from storybook/manager-api and addons from storybook/preview-api, with addons.add() as a registration mechanism. In practice, that separation helps addon authors keep UI shell code, preview instrumentation, and package metadata as distinct concerns.

The catalog metadata is the public discovery layer used after the addon package exists. The source document says the storybook-addon keyword must be the first keyword, followed by the addon's category. Additional keywords are still useful because the catalog uses them for search and tags. This ordering is important: consumers may experience the addon through search and category browsing before they ever read the package README, so metadata quality directly affects adoption and support expectations.

Sources: docs/addons/integration-catalog.mdx

Catalog Package Reference

Surface	Required or optional	Contract
`package.json.name`	Required	npm package name shown for the addon.
`package.json.description`	Required	Short description used to explain the addon's purpose.
`package.json.author`	Required	Author name for attribution.
`package.json.keywords`	Required	First keyword must be `storybook-addon`; the next keyword should be the category; remaining values become search tags.
`package.json.repository`	Required	Repository object, such as `{ "type": "git", "url": "https://github.com/someone/my-addon" }`.
`package.json.storybook.displayName`	Optional presentation metadata	Friendly display name for catalog UI.
`package.json.storybook.icon`	Optional presentation metadata	Link to a custom icon; SVG icons are not supported by the documented contract.
`package.json.storybook.supportedFrameworks`	Optional compatibility metadata	Framework identifiers that the addon supports.
`package.json.storybook.unsupportedFrameworks`	Optional compatibility metadata	Framework identifiers that the addon does not support.

The documented framework identifiers are exact string values, not labels to rewrite. Use react, vue, angular, web-components, ember, html, svelte, preact, and react-native exactly as listed when filling supportedFrameworks or unsupportedFrameworks. This exactness matters because catalog indexing depends on normalized values. If a package says web components, webComponents, or reactnative, the intent may be clear to a human but unreliable for automated catalog filtering.

Sources: docs/addons/integration-catalog.mdx

{
  "name": "storybook-addon-example",
  "version": "1.0.0",
  "description": "Outline all elements with CSS to help with layout placement and alignment",
  "repository": {
    "type": "git",
    "url": "https://github.com/chromaui/storybook-addon-example"
  },
  "author": "winkerVSbecks",
  "keywords": ["storybook-addon", "style", "debug", "layout", "css"],
  "storybook": {
    "displayName": "Outline",
    "unsupportedFrameworks": ["vue"],
    "supportedFrameworks": ["react", "angular"],
    "icon": "https://yoursite.com/addon-icon.png"
  }
}

Maintainer Workflow

Start with the addon implementation and API surface before thinking about the catalog. Manager-side code should use manager APIs for Storybook UI integration, while preview-side code should use preview APIs for story rendering behavior. Package the addon so consumers can install it from npm, configure it from their .storybook/main.js or .storybook/main.ts when appropriate, and understand the setup from the README. The catalog should then describe a working package, not compensate for unclear installation instructions or incomplete distribution output.

After the addon works locally, prepare the npm package for catalog indexing. Confirm that the published package includes README.md, /dist, root preset.js, and the metadata fields described above. Then check that keywords begins with storybook-addon and that the next keyword represents the category you want the catalog to use. Add helpful extra keywords for search, but avoid using them as a substitute for the required first keyword or for clear README instructions.

Sources: docs/addons/integration-catalog.mdx

For migration planning, treat catalog metadata and Addons API usage as separate review items. API migrations usually affect imports, runtime registration, manager UI integration, or preview configuration. Catalog migrations affect package metadata, compatibility declarations, and generated package contents. When moving an addon to a newer Storybook major version, review both sides: update API usage to the current manager and preview packages, then update metadata so the catalog accurately communicates supported and unsupported frameworks.

Consumer Guidance and Next Steps

Consumers should use the integration catalog as a discovery tool, then verify the package README for installation and configuration steps. The catalog metadata can tell you what a package claims to support, but a production adoption decision should also look at the package repository, version history, framework compatibility, and whether the addon exposes a preset or other setup path that matches your project. Because addons are npm packages, normal package hygiene still applies: pin compatible versions, review peer dependencies, and test the addon in your own Storybook.

Addon authors should read the writing-addons and configure-addons documentation next, then return to the catalog checklist before publishing. If your addon provides UI, identify whether it belongs in the manager, the preview, or both. If your addon is primarily configuration, consider whether a preset is the cleanest public integration point. Finally, keep the metadata exact and boring: the catalog can only index the fields it receives, so precise keywords and framework identifiers are part of the user experience.

Ask a question...