Writing Addons
Purpose and Scope
Storybook addons extend the development environment by adding features, changing the interface, or integrating external tools into the component workshop. This guide is for authors who want to build an addon rather than only install one. The repository documentation frames addon writing as a practical reference: build a small addon inspired by the Outline addon, learn how addons are structured, exercise Storybook APIs, test locally, and prepare the package for publishing. That makes the page useful both as a mental model and as a project plan for a first addon.
Sources: docs/addons/writing-addons.mdx
Relevant Source Files
- docs/addons/writing-addons.mdx - Primary authored documentation for the public Write an addon guide, including addon categories, the Outline-inspired example, Addon Kit setup, React compatibility guidance, and build-system notes.
Addon Anatomy
The documentation divides addons into two main categories: UI-based addons and presets. UI-based addons customize Storybook’s visible interface, add shortcuts, or display extra information while a developer browses stories. Presets are preconfigured settings that let an addon package Storybook configuration, technology integration, or other setup behavior for consumers. Keeping these categories separate helps addon authors decide whether they are building a visible user experience, a configuration package, or a package that combines both patterns.
Sources: docs/addons/writing-addons.mdx
The example in the guide is a UI-based toolbar addon. Its behavior is intentionally concrete: it lets users draw outlines around every element in the rendered story, either through a shortcut or by clicking a toolbar button. That example is based on the historical Outline addon, which later informed Storybook’s built-in outline feature. Toolbar addons are only one UI shape; the same section also points readers to panels and tabs as other ways to add interaction surfaces to Storybook’s interface.
Sources: docs/addons/writing-addons.mdx
Authoring Model and Runtime Surfaces
A useful way to reason about addon authoring is to ask where the addon participates in Storybook. The source guide names three broad interaction surfaces: presets can modify configuration, manager code can add behavior to the Storybook user interface, and preview code can affect the iframe where stories render. A toolbar addon usually needs a manager-side control so users can toggle behavior, and it may also need preview-side behavior so the rendered story can respond to that control.
Sources: docs/addons/writing-addons.mdx
The documentation also calls out an important UI constraint: addons with UI must use the same React version as Storybook. That matters because the manager interface is React-based, so bundling or depending on an incompatible React runtime can create subtle rendering and hook failures. If an addon author’s component library uses a different React version, the guide recommends building and publishing the addon as a standalone package, with the Addon Kit presented as the path used later in the guide.
Sources: docs/addons/writing-addons.mdx
Setup Flow with Addon Kit
For a first addon, the guide directs authors to the Storybook Addon Kit. The Addon Kit is described as a ready-to-use template that includes the building blocks, dependencies, and configuration required to start development. The intended flow is to create a new repository from the template, clone that repository, install dependencies, answer the setup prompts, then start Storybook in development mode while the addon builds in watch mode. This gives authors immediate feedback while they change manager, preview, or preset code.
Sources: docs/addons/writing-addons.mdx
The Addon Kit defaults to TypeScript, which is the recommended starting point for most authors because Storybook’s public APIs and package surfaces are type-heavy. The guide still acknowledges JavaScript workflows by naming an eject-ts command that converts the generated project away from TypeScript. Treat that conversion as an early project decision: switching after an addon grows can require more cleanup, while staying with TypeScript can make exported addon APIs and configuration options easier for consumers to discover.
Sources: docs/addons/writing-addons.mdx
Build System and Packaging
Addon packages in this ecosystem rely on tsup, described in the guide as a fast, zero-configuration bundler powered by esbuild. The Addon Kit includes a preconfigured tsup configuration file so authors can customize how the addon is transpiled into browser-ready modern JavaScript. This build step is not just a production detail. During development, the build configuration determines which entry points are watched, how code is emitted, and whether Storybook can load manager, preview, or preset files correctly.
Sources: docs/addons/writing-addons.mdx
Because addons can affect different parts of Storybook, packaging decisions should follow the runtime surfaces. A manager entry should be optimized for the Storybook UI, a preview entry should be safe to run beside rendered stories, and preset files should focus on configuration composition rather than visible controls. The writing guide’s sequence encourages authors to first understand the addon structure, then test locally, then publish. Following that order reduces the chance of shipping an addon that works in the template but fails for real consumers.
Sources: docs/addons/writing-addons.mdx
Practical Checklist
Use this source-backed checklist while planning an addon. First, decide whether the addon is UI-based, a preset, or a combination. Second, if it is UI-based, choose a toolbar, panel, or tab shape based on the user interaction you need. Third, create the package from Addon Kit and keep its default TypeScript setup unless your project intentionally standardizes on JavaScript. Fourth, confirm any UI code is compatible with Storybook’s React version. Finally, verify which manager, preview, and preset entry points your build must emit.
Sources: docs/addons/writing-addons.mdx
After this page, read the addon type documentation to choose the right UI extension point, then read the preset guide if your addon needs to package configuration. Authors who are preparing a real release should also review the addon installation and catalog pages so the package is easy for consumers to register and discover. The important next step is to keep the example small: reproduce the Outline-style toggle first, prove it works locally, and only then add options, integrations, or publishing polish.
Sources: docs/addons/writing-addons.mdx