shilman/storybook-webpack5-experimental.md

## storybook-webpack5-experimental.md

      
    Raw
  

              storybook-webpack5-experimental.md
            
          
⚠️ Warning: this document is out of date.
For the most recent webpack5 instructions see MIGRATION.md.

Storybook experimental Webpack 5 support

Storybook 6.2 includes experimental Webpack 5 support. Webpack 5 brings a variety of performance improvements, as well as exciting new features like module federation. Here's a quick guide to get you going.
Intro

Storybook uses webpack to bundle its UI ("manager") and also user code in an iframe ("preview"). In Storybook 6.2, the manager is bundled in Webpack 4, and the preview can either be bundled in Webpack 4 (default) or Webpack 5 (opt-in). In Storybook 6.3, the manager is also bundled in Webpack 5 when the preview is bundled with Webpack 5.

The main 6.2 PR: storybookjs/storybook#13808
The main 6.3 PR: storybookjs/storybook#15001

Installation

NOTE: Before you try out Storybook's webpack5 support, make sure your project works with Webpack 5. For example, create-react-app v4 (CRA v4) is not webpack5-compatible, so if you have a CRA project, you'll need to upgrade to CRA v5 which uses webpack5. Once you've verified webpack5 in your project, you can either do a clean install or an upgrade.
Upgrading from Webpack 4

If you're upgrading an existing Storybook installation:
npx sb@next upgrade --prerelease
Then add dependencies:
npm i -D @storybook/builder-webpack5@next @storybook/manager-webpack5@next webpack@5

Note that the webpack@5 dev dependency forces webpack5 to be hoisted, since SB also contains a webpack4 dependency

Then update your .storybook/main.js:
module.exports = {
  core: {
    builder: "webpack5",
  },
};
Upgrading from 6.2 Webpack 5

If you were using Webpack 5 in 6.2, and have upgraded to 6.3, you probably need to add @storybook/manager-webpack5 as a dependency:
npm i -D @storybook/manager-webpack5@next
Clean install

If your project doesn't have Storybook installed:
npx sb@next init --builder webpack5

This adds storybook and automatically performs the extra steps descripted in the "Upgrade from Webpack 4" section.
Troubleshooting

Currently all storybook addons assume webpack 4. If you run into issues, try disabling addons and see if that fixes it. If you find an addon that needs to be upgraded to support Webpack 5, please file an issue and let us know!
Webpack 5 support is still experimental. If you run into problems, please check to see if somebody's already filed an issue Storybook repo and upvote it if there's an existing issue. If there's no existing issue, please file one and title it Webpack5: (problem summary).
Yarn resolutions

Some webpack5 projects are using Yarn resolutions to force a specific version of webpack across the entire project. We don't recommend this because it causes problems for Storybook which still uses webpack4 to build its "manager" UI (not user code). However, if you must use resolutions including all of the following packages is a workaround seems to patch over the issue:
{
  "resolutions": {
    "webpack": "^5.0.0",
    "css-loader": "^5.0.0",
    "dotenv-webpack": "^6.0.0",
    "html-webpack-plugin": "^5.0.0",
    "style-loader": "^2.0.0",
    "terser-webpack-plugin": "^5.0.0",
    "webpack-dev-middleware": "^4.1.0",
    "webpack-virtual-modules": "^0.4.2"
  }
}

We're considering a proper solution in #14044.