Using Storybook#

Storybook is a tool dedicated to component debugging, providing around component development.

• Develop UIs that are more durable
• Test UIs with less effort and no flakes
• Document UI for your team to reuse
• Share how the UI actually works
• Automate UI workflows

Before when using Storybook, there are various problems related to configurations, Babel, Webpack, less or sass. Modern.js integrates with Storybook, which greatly simplifies configuration for us as we develop our Storybook project.

V7 (Recommended)#

Enable Storybook#

You can directly enable the Storybook feature by using the following command:

$ npx modern new
? Please select the operation you want: Enable features
? Please select the feature name: Enable「Storybook」V7

This command will create a template for Storybook, including:

• Creating a configuration folder .storybook and a default configuration file .storybook/main.ts.
• Creating example story components.
• Updating package.json to add dependencies @storybook/addon-essentials and @modern-js/storybook, as well as creating Storybook-related scripts.

Enable Debug output#

In fact, Modern.js Module is implemented based on esbuild, while Storybook uses Webpack as the default build tool, and their configurations are not fully compatible. Therefore, we recommend building the components first, and then importing the component output in stories.

The way to import component outputs is very simple. Suppose your module exports a Button component, then you can use it in stories like this:

import { Button } from '.';

export const YourStory = () => <Button />;

export default {
  title: 'Your Stories',
};

If you want to update the components, you can start the build in watch mode before starting Storybook:

modern build --watch

{
    "name": "foo",
    "main": "./dist/index.js",
    "types": "./src/index.ts",
    "publishConfig": {
      "types": "./dist/index.d.ts",
    }
}

Enable Rspack build#

Rspack is known for its fast build speed. To use Rspack as a build tool in Modern.js, you only need to configure it as follows:

const config = {
  framework: {
    name: '@modern-js/storybook',
    options: {
-      bundler: 'webpack'
+      bundler: 'rspack'
    },
  },
  typescript: {
-    reactDocgen: 'react-docgen-typescript'
+    reactDocgen: 'react-docgen'
  }
};

export default config;

Note that in the above configuration, the reactDocgen configuration has been changed because Rspack currently does not support @storybook/react-docgen-typescript-plugin.

Configurations#

There are some separate configurations in .storybook/main.js.

bundler#

• Type: 'webpack' | 'rspack'
• Default: webpack

Specify the underlying bundler to use either Webpack or Rspack.

Example:

const config = {
  framework: {
    name: '@modern-js/storybook',
    options: {
      bundler: 'rspack',
    },
  },
};

export default config;

builderConfig#

• Type: BuilderConfig
• Default: undefined

The Storybook build capability of Modern.js is provided by Rsbuild, and the Rsbuild configuration can be modified through builderConfig.

const config = {
  framework: {
    name: '@modern-js/storybook',
    options: {
      builderConfig: {
        alias: {
          react: require.resolve('react'),
          'react-dom': require.resolve('react-dom'),
        },
      },
    },
  },
};

export default config;

Command#

@modern-js/storybook proxies some storybook cli commands

storybook dev#

Start Storybook,detail

storybook build#

Build Storybook for production,detail

Migrate from V6 to V7#

Our support methods for the two versions are different, so if you are migrating from V6 to V7, we hope you will also use V7 in the same way, while making the following adjustments:

• Configuration file: Migrate any custom configurations (if any) in the original root/config/storybook/main.(j|t)s to the new root/.storybook/main.(j|t)s.
• Dependencies: Upgrade @storybook/addon-* series dependencies (if any) to version 7 and delete @modern-js/plugin-storybook dependencies.
• Commands: Delete the original edenx dev storybook and edenx build --platform commands. If you are used to the original pnpm run dev usage, you can replace it with storybook dev -p 6006 and storybook build.
• modern.config.(j|t)s : Remove the registration of @modern-js/plugin-storybook plugin.

V6 (legacy)#

Starting from 2.40.0 version, @modern-js/plugin-storybook will stop iterating. It is recommended to use the V7 version. If your @modern-js/module-tools version is lower than 2.40.0, you can use Storybook V6 in the following ways:

Start Storybook#

You can directly use the following command to enable the Storybook feature.

$ npx modern new
? Please select the operation you want Enable optional features
? Please select the function name Enable "Storybook"

This command will create commonly used templates for Storybook, including

• Create stories component examples
• Update package.json, add a dependency on @modern-js/plugin-storybook, and add related scripts such as pnpm dev storybook.

Configure Storybook#

The Storybook official configures the project through a folder named .storybook, which contains various configuration files. In Modern.js Module, you can add Storybook configuration files in the project's config/storybook directory.

For how to use various Storybook configuration files, you can check the following link:

• Configure Storybook

However, there are some restrictions when using it in module projects:

• Cannot change the location where Story files are stored, that is, the stories configuration cannot be modified in the main.js file.
• Cannot modify the configuration related to Webpack and Babel, that is, the webpackFinal and babel configurations cannot be modified in the main.js file.

Build Storybook Output#

In addition to debugging the component or ordinary modules with Storybook, you can also use the following command to execute the Storybook build task.

modern build --platform storybook

After the build is complete, you can see the build output files in the dist/storybook-static directory.