Storybook: migrate to 7.X using Web Storybook Builder

[florian-sanders-cc]

Context

We are currently using Storybook 6.4.9 thanks to the Storybook prebuilt package provided by Modern Web.

Recently, Storybook 7 has been released, along with a Storybook builder API.

This API aims at easing the use of a dev server and / or bundler other than the ones already packaged (Webpack & Vite).

Modern Web has released a Web Storybook builder thanks to which we could keep on using the Web Dev Server and Rollup to serve and build our Storybook + upgrade to Storybook 7.

Even if it's still WIP, we want to try and use it to:

• benefit from storybook 7:
  • lazy loading of stories by default for instance,
  • config files using ESM instead of CJS 🙌.
• move away from the opiniated storybook prebuilt (though it's good and we enjoy using it, it would be great to get closer to Storybook "standard" and manager our Storybook Addons directly for instance).

What we've done so far (success & issues)

Using the Storybook migration tool

• Tried to follow the migration guide by Modern Web:
  • run npm install @storybook/builder-vite@0.4 @storybook/web-components@6 --save-dev to make as if we were using vite & the web components framework.
  • run npx storybook@latest upgrade.

The upgrade failed: ❌ Failed trying to evaluate .storybook/main.js with the following error: No "exports" main defined in /home/flo/Projects/clever-components/node_modules/@web/dev-server-storybook/package.json

We decided not to go further with this approach and start from scratch.

Going for a fresh install

• Uninstall the @web/dev-server-storybook package,
• Backup our .storybook folder containing our config,
• Install storybook using the storybook cli as advised in the Storybook Builder: Configuration - Modern Web
• Kept on following the Storybook Builder: Configuration - Modern Web.
• Since we have uninstalled @web/dev-server-storybook, we have to disable the storybookWdsPlugin() from our WDS plugins,
• There seems to be an issue with HMR which I don't understand (didn't search though): Error: Cannot use HMR when web sockets are disabled. => I disabled (commented) the HMR plugin
• Adapt to the breaking change with the story sorting function (https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#v7-style-story-sort)
• Adapt the manager.js file. Instead of import { ... } from '@web/storybook-prebuilt/....js' => import { ... } from '@storybook/....js
• When listing md stories, the indexer fails. I have a workaround with the next indexerAPI but then I fail to load the stories
  • => managed to make it work with the new experimental_indexers API: [RFC] Indexer API storybookjs/storybook#23176 + by adapting our markdown.cjs to a WDS plugin.
  • Issue when generating autodocs for components. Set it to true but should probably set it to tags and update make-story.js + it failed to load because it was relying on tocbot which uses a require even though it's run within the browser? I had to list tocbot in our WDS commonjs plugin.
• Issue with our storybookMenuSort function. Storybook sortStory value must be inlined directly within the preview parameters, it cannot be imported from a file or even a local variable:
  
  => The good news is that we can use the order property to directly pass the menu we want and storybook now sorts it for us. This allows us to remove some of our code so it's good news in the end.
  This also fixed the order of the component stories which are now back to the export order.
• issue with preview-head.html links to external CSS => this file is merged with another inside a iframe.html file. The builder does not process the preview-head.html with rollup-plugin-html which means that CSS dependencies are not processed (files are not copied to assets + link paths are not updated). I tried many things that didn't work. In the end I used staticDirs as follows:

staticDirs: [
    {
      from: '../src/styles/default-theme.css',
      to: 'styles/default-theme.css',
    },
    {
      from: '../node_modules/highlight.js/styles/vs.css',
      to: 'styles/vs.css',
    },
    {
      from: '../node_modules/github-markdown-css/github-markdown.css',
      to: 'styles/github-markdown.css',
    }
  ],

• issue with docs from templates / controllers / mixin => we don't build doc stories like before (and I didn't manage to make it work the old way with the new indexer API). I switched to docs with front matter loaded like other .md stories. The only downside is that they don't have the same icon as the others + they are listed as the last story 😞
• issue with the build => I had forgotten to add the commonJS plugin. Should use the common from rollup
• issue with enhanceStoriesNames => Storybook autodefines story names based on the export name. If you want to set a custom name, you can use the name property inside a story. Our enhanceStoriesNames relied on storyName (dunno if it was the old way to do this or something I misunderstood). I tried changing storyFn.storyName to storyFn.name but it throws an error saying the name is a readonly property (which makes sense because now we lazy-load stories and build an index).
  => There is another way to achieve what we had before: use renderLabel from the manager to enhance story names.

renderLabel: ({ name, type }) => type === 'story' ? enhanceStoryName(name.toLocaleLowerCase()) : name,

• the builder still shows warning about md storyfiles even though it's properly handled (thanks to custom indexers). This is a limitation of the builder, we need to open an issue (or even a PR).

Other stuff to test/fix:

• staticDirs to serve our brandImage,
• a dark vs light theme (logo)
• autodocs with tags instead of true
• fix enhanced Story names
• fix the build (start tweaking rollupFinal)
  • use common commonjs rollup plugin (preconfigured)
  • fix autogenerated docs not working when built 😭
  • fix story order for docs in templates, controllers, etc.
• there might be a better way to handle markdown: https://storybook.js.org/docs/web-components/writing-stories/build-pages-with-storybook
• create an issue about the warning when we handle story files with a custom indexer (for md for instance).
• check refs in config, could it be useful for us?