New
Storybook’s Visual Tests addon enters betaVisual test with Chromatic
Star82,041

Addon migration guide for Storybook 7.0

Storybook 7 is our first major release in over two years. While Storybook’s addon API has not changed much in the past couple of years, addons require several changes for compatibility with Storybook 7. This guide will walk you through the upgrade process.

As we gather feedback from the community, we’ll update this page. We also have a general Storybook migration guide if you’re looking for that.

Dependencies

The first thing to do is upgrade any Storybook dependencies in your project. We release the next version of all our packages on the next npm tag, so the easiest thing is to reference that in your package.json:

Loading...

If you'd rather depend on the latest version of Storybook, you can use the latest tag:

Loading...

Or use a version specifier:

Loading...

Breaking changes

@storybook/addons has been split into @storybook/manager-api and @storybook/preview-api

The default export from @storybook/addons can now be used via named imports from @storybook/manager-api and @storybook/preview-api, depending on which environment you need the API from. The manager is the Storybook UI and includes your addon's Addon Panel. While the preview is used to render stories and includes your addon's decorators.

You might also depend (and use) these packages in your addon's decorators: @storybook/store, @storybook/preview-web, @storybook/core-client, @storybook/client-api. These have all been consolidated into @storybook/preview-api. If you use any of these packages, please import what you need from @storybook/preview-api instead.

Some components were moved from @storybook/components to a new package @storybook/blocks

Components like ColorControl, ColorPalette, ArgsTable, ArgRow, TabbedArgsTable, SectionRow, Source, AND Code were moved into a new package. In Storybook 7.0, they should be imported from @storybook/blocks instead.

import { ColorControl } from '@storybook/components';
Loading...

Deprecations and detailed migrations

We’ve also deprecated a few packages and APIs in 7.0. After you’ve made your addon working with 7.0, make sure to check the browser console in a Storybook running your addon. If you’re using deprecated packages, you should see warnings that link to migration instructions.

There are more technical details available in the migration notes for addon authors.

Finally, for an exhaustive list of noteworthy changes in 7.0, check the full migration notes.

Releasing

You should release a new major version of this addon that supports Storybook 7. If you want to continue making changes that support Storybook 6, you should release a minor or a patch of the previous major version.

We also recommend releasing your own addon using the next tag to test it out in projects.

Support

If you're still having issues with your addon after following this guide, please open a new discussion in our GitHub repository.

Was this page helpful?

Markdown accepted ([link text](url), _italic_, **bold**, etc). Your anonymous feedback will be posted publicly on GitHub.

✍️ Edit on GitHub – PRs welcome!
Storybook
Join the community
6,490 developers and counting
WhyWhy StorybookComponent-driven UI
Open source software
Storybook

Maintained by
Chromatic
Special thanks to Netlify and CircleCI