---
sidebar_position: 5
---

# Using Storybook

[Storybook](https://storybook.js.org/) 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:

```bash
$ 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:

```ts filename="stories/index.stories.tsx"
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:

```bash
modern build --watch
```

:::info
In the development process, you may encounter situations where you cannot get type definitions in real time. Because only when the code is saved, the type file under the output directory will be updated. At this time:

For `pnpm` projects, you can modify the `package.json` as follows:

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

> For the use of `publishConfig` in pnpm, you can read the following [link](https://pnpm.io/package_json#publishconfig).

For npm and Yarn projects, the `types` value of `package.json` can only be modified manually during the **development stage** and **release stage**.
:::

### 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:

```diff filename='.storybook/main.js'
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:

```javascript filename='.storybook/main.js'
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](https://rsbuild.dev/), and the Rsbuild configuration can be modified through builderConfig.

```javascript filename='.storybook/main.js'
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](https://storybook.js.org/docs/react/api/cli-options#dev)

#### storybook build

Build Storybook for production,[detail](https://storybook.js.org/docs/react/api/cli-options#build)

## 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 `MAJOR_VERSION.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 `MAJOR_VERSION.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.

```bash
$ 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](https://storybook.js.org/docs/react/configure/overview)

**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.

```bash
modern build --platform storybook
```

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