addons/publishing

54 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Addon catalog metadata: package.json properties

The package.json must include the following addon metadata properties in the storybook object: displayName (display name for the addon), icon (link to custom icon for the addon in PNG, JPG, or other formats but not SVG), unsupportedFrameworks (list of unsupported frameworks), and supportedFrameworks (list of supported frameworks). The addon is identified using the name, description, author, keywords, and repository properties at the root level.

Addon keywords requirement

In the package.json keywords array, the first keyword must be 'storybook-addon' followed by your addon's category. Additional keywords will be used in search and as tags in the catalog.

Supported Storybook frameworks list

When specifying supportedFrameworks and unsupportedFrameworks in the addon metadata, use these exact framework names: react, vue, angular, web-components, ember, html, svelte, preact, react-native. Each item must be copied exactly as listed for proper catalog indexing.

Addon metadata table specification

Addon metadata in package.json root level: name (addon package name, type string, example 'storybook-addon-example'), description (addon description, type string), author (name of the author, type string), keywords (list of keywords to describe the addon, type array, example '["storybook-addon","style","debug"]'), repository (addon repository, type object with type and url, example '{"type": "git","url": "https://github.com/someone/my-addon"}'). Storybook property metadata: displayName (display name, type string, example 'Example'), icon (link to custom icon for the addon excluding SVG, type string, example 'https://yoursite.com/addon-icon.png'), unsupportedFrameworks (list of unsupported frameworks, type array, example '["vue"]'), supportedFrameworks (list of supported frameworks, type array, example '["react", "angular"]').

Addon catalog requirements

To publish a Storybook addon to the integration catalog, the npm package must include: a package.json file with module information and addon metadata, a README.md file with installation and configuration instructions, a /dist directory containing transpiled ES5 code, and a preset.js file written as an ES5 module at the root level.

Example package.json for addon catalog

{ "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" } }

Addon catalog appearance time

Once you publish an addon to npm, it will appear in the Storybook integration catalog. There may be a slight delay between the time you publish your addon and when it's listed.

Verify addon npm metadata command

To confirm that the latest npm version includes the catalog metadata for your addon, run: npm view your-addon-package-name --json

Addon missing from catalog troubleshooting

If your addon doesn't appear in the catalog after a short period, verify it includes all required fields, keywords, and information. If everything looks correct but your addon is still missing, open an issue in the Storybook documentation repository at https://github.com/storybookjs/web, including the npm package URL with the latest version, the package repository, and the output from the npm view command.

Storybook recipes definition

Recipes are a set of instructions to integrate third-party libraries into Storybook in cases where an addon does not exist or the integration requires some manual effort.

Storybook recipes ownership

Recipes are written and maintained by the Storybook team. Recipes are created based on community popularity, tool maturity, and stability of the integration to ensure that recipes continue to work over time.

Request a Storybook recipe

To request a recipe, open a new discussion in the Storybook GitHub repository at https://github.com/storybookjs/storybook/discussions/new?category=ideas. The Storybook team will review the request and if it's popular, add it to the backlog and prioritize it.

Storybook must be published and publicly accessible to embed

In order to use embeds, your Storybook must be published and publicly accessible.

Storybook supports iframe embeds out of the box

Storybook supports iframe embeds out of the box.

Chromatic supports oEmbed standard for platform integration

If you use Chromatic to publish Storybook, you can also embed stories in Notion, Medium, and countless other platforms that support the oEmbed standard.

iframe embed parameters for story with toolbar

To embed a story with the Storybook toolbar, use an iframe with the published story URL and the following query parameters: full=1, shortcuts=false, and singleStory=true. The path parameter should be set to /story/{component}--{story}. Example: <iframe src="https://example.chromatic.com/?path=/story/shadowboxcta--default&full=1&shortcuts=false&singleStory=true" width="800" height="260"></iframe>

iframe embed parameters for story without toolbar

To embed a story without Storybook's toolbar, use an iframe with the canvas URL using the /iframe.html path and the following query parameters: id={component}--{story}, viewMode=story, shortcuts=false, and singleStory=true. Example: <iframe src="https://example.chromatic.com/iframe.html?id=shadowboxcta--default&viewMode=story&shortcuts=false&singleStory=true" width="800" height="200"></iframe>

Embed documentation pages with viewMode=docs

To embed documentation pages instead of stories, replace viewMode=story with viewMode=docs and use the auto-generated documentation entry id for the story (typically {component}--docs). Example: <iframe src="https://example.chromatic.com/iframe.html?id=shadowboxcta--docs&viewMode=docs&shortcuts=false&singleStory=true" width="800" height="400"></iframe>

Get canvas URL for embedding without toolbar

To get the canvas URL for embedding a story without Storybook's toolbar, click the 'open canvas in new tab' icon in the top-right corner of Storybook.

Medium embeds become interactive after article publication

When embedding Storybook in Medium, the embeds render as non-interactive while editing an article. Once the article is published, the embed becomes interactive. The embed will automatically resize to fit the story's height.

Embed in Notion using /embed command

To embed in Notion, type /embed in your Notion document, press Enter, and paste the story URL as the embed link. You can resize the embed as necessary.

Embed in Ghost using /html command

To embed in Ghost, type /html in your Ghost post, press Enter and paste the iframe URL. You can resize the embed via the width and height properties as required.

Platform embed support varies

Every platform has different levels of embed support. Check the documentation of your service to see how they recommend embedding external content.

Storybook Composition for browsing multiple Storybooks

Composition lets you browse components from any other Storybook—published or running locally—inside your own Storybook's sidebar. It works across renderers and tech stacks, making it useful for referencing a design system, auditing component usage across projects, or viewing multiple Storybooks in one place.

Share button for quick Storybook sharing

The Share button in the Storybook UI generates a link to your Storybook that you can share with anyone without needing to set up a hosting solution. This sharing feature is provided by Chromatic's Visual Tests addon.

Publish Storybook as static web app

You can build Storybook as a static web app and deploy it anywhere you host static sites. A published Storybook gives developers, designers, PMs, and other stakeholders a shared URL to review work in progress without a local dev environment. Free hosting options include Chromatic for review and visual testing workflows, or services like GitHub Pages, Netlify, or AWS S3.

Embed individual stories with iframes

Once your Storybook is published and publicly accessible, you can embed individual stories in other pages. Storybook supports iframe embeds out of the box. Storybooks published to Chromatic also work with the oEmbed standard, allowing stories to render inline in Notion, Medium, and other oEmbed-compatible platforms.

Storybook Figma integration

Storybook integrates with Figma. You can embed Storybook stories in Figma to compare designs against the real components, or embed Figma frames in Storybook to reference designs alongside the components that implement them.

Configure package for automatic Storybook Composition

Design system and component library authors can configure their package so that consumers automatically see the library's stories alongside their own when they install it. This gives consumers usage documentation in context without leaving their Storybook.

Add storybook property to package.json for composition

Component library authors enable package composition by adding a storybook property to their published package.json. This property must contain an object with a url field that points to a published Storybook at the version to be composed.

Package composition package.json configuration example

Add the following to package.json to enable package composition: ```json { "storybook": { "url": "https://host.com/your-storybook-for-this-version" } } ```

Publish Storybook to Chromatic for full package composition support

Composition via a package requires a secure integration between the service where you publish Storybook and Storybook's own APIs. Publishing Storybook to Chromatic is recommended for full support of package composition features.

Automatic version selection with Chromatic

When using Chromatic, authors can provide a single master URL for their Storybook in the storybook.url field and do not need to change the URL each time a new version is published. Storybook will automatically find the correct URL for the package corresponding to the version the user has installed. The Chromatic project id must be included in the URL.

Automatic version selection with Chromatic example

When using Chromatic, configure package.json as follows: ```json { "storybook": { "url": "https://master--xyz123.chromatic.com" } } ``` Replace xyz123 with your Chromatic project id. Storybook will automatically compose the Storybook published to that project corresponding to the version the user has installed.

Show version selector for package composition

When using Chromatic, authors can provide a list of versions for users to choose from, allowing consumers to experiment with different versions of the package.

Consumers can switch versions of composed Storybooks

With appropriate configuration from the package author, consumers can change the version of a composed Storybook to see how the library evolves.

Package composition enables design system stories in consumer Storybooks

Design system authors can automatically compose their design systems inside their consumer's Storybooks. When a consumer installs a package that supports composition, its stories appear alongside the consumer's own stories. This allows cross-referencing usage documentation without leaving Storybook.

Install Chromatic CLI from npm

Install the Chromatic CLI package from npm using `npm install chromatic` or similar package manager commands.

Deploy with Chromatic CLI

Run `npx chromatic --project-token=<your-project-token>` to deploy your Storybook to Chromatic. Replace `<your-project-token>` with your own unique project token.

Setup GitHub Actions for Chromatic CI

Configure CI to automatically publish Storybook by adding a `chromatic.yml` workflow file in the `.github/workflows` directory. Use GitHub Secrets to securely store your project-token environment variable instead of hardcoding it.

UI Review feature in Chromatic

When publishing to Chromatic, use the UI Review feature to automatically scan PRs for new and updated stories, making it easy to identify changes and gather team feedback.

Chromatic provides component versioning and history

Chromatic automatically tracks component history and versioning down to the commit, useful for comparing components between branches, commits, and past versions during implementation review.

Publish Storybook to multiple hosting services

Since Storybook is built as a static web application, it can be published to any web host including GitHub Pages, Netlify, AWS S3, and others. However, features like Composition, embedding stories, history, versioning, and assets may require tighter integration with Storybook APIs and secure authentication.

Deploy Storybook to GitHub Pages with community Action

Use the community-built Deploy Storybook to GitHub Pages Action from bitovi. Create a new workflow file inside `.github/workflows` directory to enable it. The action requires additional configuration options for customization.

Component Publishing Protocol levels

CPP level 1 services serve published Storybooks with versioned endpoints, `/index.json` endpoint support for stories metadata, and `/metadata.json` with releases field. CPP level 0 services can serve published Storybooks with no further Storybook API integration. Chromatic is CPP level 1; Netlify and S3 are CPP level 0.

Add SEO description to manager-head.html

To provide a description for search engines, add a meta description tag to the `manager-head.html` file in your config directory.

Prevent Storybook from being crawled by search engines

To prevent your published Storybook from appearing in search engine results, include a noindex meta tag by adding it to the `manager-head.html` file in your config directory.

Build Storybook as static web application

Run `npm run build-storybook` in your project's root directory to build Storybook as a static web application. The functionality is pre-configured for most supported frameworks.

Preview production build locally

After building Storybook, run `npm run serve-storybook` or similar command to preview the production build locally before publishing.

Angular builder for Storybook production build

If using Angular, use the Angular builder instead of the default build command to build Storybook for production.

Customize production build with test option

To optimize production build performance for larger projects or faster build times, use the `test` option in your `main.js|ts` configuration file and add the `--test` flag to your build script.

Preview-only mode for older browsers

Use the `--preview-only` CLI flag to build Storybook in preview-only mode, which skips building the Storybook manager UI and only builds the preview iframe. This allows your Storybook builder configuration to determine which browsers are supported.

Access preview-only Storybook at iframe.html

When using preview-only mode, the normal entry point `/index.html` results in a 404 error because the client-side router is not available. Instead, access the preview at `/iframe.html?navigator=true` which renders a basic HTML-only sidebar for story navigation. For example: `http://localhost:6006/iframe.html?navigator=true`.

Chromatic as recommended publishing service

Chromatic is a free publishing service made for Storybook that documents, versions, and indexes UI components securely in the cloud. To use Chromatic, sign up with GitHub, GitLab, Bitbucket, or email and generate a unique project-token.

Give your agent this brain