Storybook 4 Migration Guide

This step-by-step guide gets you migrated to Storybook 4.0 (SB4).

You’re probably here because you’ve heard about all the great stuff in SB4 and want to know how to upgrade existing project. Or because you already tried upgrading and it didn’t go your way. Either way, you’re in the right place.

The biggest breaking changes in SB4 are an upgrade from Webpack 3 to 4 and another from Babel 6 to 7. Therefore we take you through the following steps:

1. Upgrading the Storybook package
2. Dealing with Webpack 4 / Babel 7 issues if you have them
3. Dealing with addons and minor breaking changes

We also provide follow-up steps at the bottom if the guide doesn’t work for you — we have an awesome community that’s ready to help you out.

NOTE: React Native is its own kettle of fish, and has its own kick-ass guide.

Step 1: Package Upgrade

The first thing to do is upgrade your Storybook packages, @storybook/*. If you’re using yarn you can interactively upgrade like this:

yarn upgrade-interactive --latest

Or if you’re using npm, this voodoo will do the trick:

npx npm-check-updates '/storybook/' -u && npm install

NOTE: Storybook currently requires React 16.3 and above. If you’re developing React components, this means you need to upgrade to 16.3 or higher to use Storybook 4.0. If you’re using Storybook for anything other than React, you probably don’t need to worry about this.

UPDATE: We’ve updated Storybook 4.1 to restore React 15.x compatibility. Go team!

The error you’ll get if you’re running an older version of React:

core.browser.esm.js:15 Uncaught TypeError: Object(...) is not a function    at Module../node_modules/@emotion/core/dist/core.browser.esm.js (core.browser.esm.js:15)    at __webpack_require__ (bootstrap:724)    at fn (bootstrap:101)    at Module../node_modules/@emotion/styled-base/dist/styled-base.browser.esm.js (styled-base.browser.esm.js:1)    at __webpack_require__ (bootstrap:724)    at fn (bootstrap:101)    at Module../node_modules/@emotion/styled/dist/styled.esm.js (styled.esm.js:1)    at __webpack_require__ (bootstrap:724)    at fn (bootstrap:101)    at Object../node_modules/@storybook/components/dist/navigation/MenuLink.js (MenuLink.js:12)

Then try running Storybook:

yarn storybook

If the browser opens and things generally look OK, you’re most of the way there, and you can skip to Step 3.

Step 2: Webpack/Babel Upgrades

If Step 1 failed and you don’t see Storybook running in your browser, the next step is to figure out why. One likely culprit is Storybook’s Babel 7 upgrade. Common project types that use Babel 6 and will break include: create-react-app v1 (CRA1) projects, NextJS 6 projects, and Gatsby v1 projects.

But it could be lots of things, so let’s find out. If you don’t see an error message in your terminal, check for an error message in your browser console. Here’s the typical Babel error you’d see on the console if your project is on Babel 6:

{ Error: Cannot find module 'babel-loader/package.json' 
   ... long stack trace
}

If your project is running Babel 6, you have a few options:

1. Upgrading your project (e.g. CRA 1 to 2 , Next 6 to 7, or Gatsby 1 to 2)
2. Not upgrading your project, but upgrading Babel
3. Continuing on Babel 6 and relying on Babel’s backward compatibility.

We suggest upgrading to Babel 7 unless your project is somehow tied to Babel 6. It’s the future, and all the cool kids are doing it.

Option 1: Upgrading your project

Suppose you are using a framework which uses Babel 6 (e.g. CRA1, Next6, or Gatsby1). The best thing you can do to get Storybook 4 compatibility is to upgrade your project to the latest version, which uses Babel 7. Web frameworks are constantly improving, so why not get the latest and greatest?

To do this, verify that there is a new version of that project type that uses Babel 7. Then follow the project-specific instructions to upgrade. To save you time, here are the links for CRA/Next/Gatsby:

• Upgrade from CRA 1 to 2
• Next 7 announcement
• Gatsby: Migrating from v1 to v2

NOTE: As far as we know, Gatsby v1 won’t work with SB4, so upgrading to v2 is your best bet.

Option 2: Upgrading to Babel 7 only

If you are unable to upgrade your project for some reason, you should also be able to upgrade to Babel 7 only within your existing project with the following commands:

yarn remove babel-core babel-runtime
yarn add @babel/core babel-loader --dev

If you use babel presets and plugins, you’ll have to upgrade those as well. Babel is a full-featured platform and has its own has its own upgrade guide which you can consult for help upgrading.

Option 3: Continuing on Babel 6

If you’re unable to upgrade to Babel 7 because you are using some Babel 6-specific features, you should be able to use babel-loader 7 to get forwards-compatibility:

yarn add babel-loader@7

Also make sure you have a .babelrc in your project, which you probably already do if you’re choosing this option. Here’s a minimal one for a React project:

{ "presets": ["env", "react"] }

Step 3: Addons and “minor” breaking changes

If your storybook appears to be running OK, you’re on the home stretch! Here are a few more things you should know.

If you use any of the addons, SB4 greatly improves addon convenience. The old API still works, but you’ll get deprecation warnings, and it’s worth taking a few minutes to upgrade. The improvements are:

1. Generic addons that are not tied to specific view layers.
2. Addon decorators that are configured by story parameters.

Generic addons

Let’s first take a look at generic addons. This 3.x code imports from a react-specific API for the knobs addon:

import { number } from “@storybook/addon-knobs/react”;

In SB4 this becomes:

import { number } from “@storybook/addon-knobs”;

Better, right? And it’s an easy fix. For more info see the full migration docs.

Story parameters

Now let’s take a look at addon decorators with story parameters. SB4 introduces story parameters, and we’ve updated all the core addons to use them.

In 3.x using addons were implemented like wrapper functions:

storiesOf('My component', module)
  .add('story1', withNotes('some notes')(() => <Component ... />))
  .add('story2', withNotes('other notes')(() => <Component .../>))

Now in 4.0 this becomes:

// .storyook/config.js (global decorator, local also supported)
addDecorator(withNotes)

// Component.stories.js
storiesOf('My component', module)
  .add('story1', () => <Component />, { notes: 'some notes' })
  .add('story2', () => <Component />, { notes: 'other notes' })

The story parameters correspond directly to the old withX arguments, so it’s easy to migrate your code. For more information see the full migration docs.

Small breaking changes

In addition to updating your addons, there are a number of small breaking changes you should know about. If any of these apply to your project, they should require minimal updates to fix.

Here’s a checklist to help get you updated quickly:

✅ Do you use Keyboard shortcuts? We’ve improved them in SB4.

✅ Do you use addon-info? We’ve removed addWithInfo.

✅ Do you use addon-knobs? We’ve changed its select behavior and also how it saves URLs.

✅ Do you use addon-storyshots? There are a few API changes you should know about. Specifically if you include stories using webpack’s require.context, you will need babel-plugin-require-context-hook.

✅ Do you run storybook in CI? start-storybookpops up a browser now, but you can disable this with the --ci flag.

✅ Do you use Typescript with ts-loader? If so, you’ll probably need to upgrade that to a post-4.0 version which supports webpack 4.

✅ Do you use the getstorybook CLI? We’ve improved the CLI and now you can initialize a new project withsb init.

And there you go! That wasn’t too bad was it?

And it’s a wrap!

Hopefully at this point you’ve successfully upgraded to SB4. If so, congratulations and welcome to the future of component development!

If you had problems getting through this guide, or made it through the guide but still have problems, please take the following steps:

1. Search for your problem in our Github issues — somebody else might have run into the same problem.
2. Create a new issue describing your problem, ideally with a link to a public repo where we can reproduce the issue.
3. Join us in our public Discord and ask a question on the #support channel. We are a friendly community and want to help you get upgraded.

— With ❤️ from the Storybook team