---
sidebar_position: 5
---

# Using Storybook

First of all, if you haven't read the following, take a few minutes to understand it first.

- [use micro-generator to enable Storybook debugging](/en/guide/basic/use-micro-generator#storybook-debug)
- [`modern dev`](/en/guide/basic/command-preview#modern-dev)

[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

So Storybook is a complex and powerful tool.

Module Tools is integrated with Storybook, so you can pretty much follow the official Storybook documentation. However, there are still a few things to keep in mind, which are explained below.

## Debugging code

The project code needs to be introduced during the debugging process and can currently be introduced in two ways:

- Use of project products
- Using the project source code

We recommend using the first "**referenced project product**" approach. Because it is closer to the real usage scenario, not only can we debug the component functionality, but also verify the correctness of the build product. However, we can also refer to the source code when testing the project functionality and refer to the project package name when verifying the project product.

Next, we will talk about how to use each of these two methods.

### Referencing component products

If the TypeScript project `foo` exists.

<CH.Spotlight>

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

---

Make sure the `main` and `types` of `package.json`
values are real paths.

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

---

The source code of the `foo` project.

```ts src/index.ts
export const content = 'hello world';
```

---

Make sure that the `paths` configuration pointing to the project root is set in `stories/tsconfig.json`.
The `key` of `paths` is the same as the project name.

```json stories/tsconfig.json focus=7:9
{
  "extends": "../tsconfig.json",
  "include": ["./"],
  "compilerOptions": {
    "jsx": "preserve",
    "baseUrl": ".",
    "paths": {
      "foo": ["../"]
    }
  }
}
```

---

Referenced directly in Story code by the project name.

```tsx stories/index.stories.tsx focus=1:1
import { content } from 'foo';

const Component = () => <div>this is a Story Component {content}</div>;

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

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

---

Finally, when executing the command, first start the source build in listening mode and then start Storybook debugging.

<CH.Code>

``` bash terminal-1
## Source Code Build
modern build --watch
```

---

``` bash terminal-2
## Storybook Debug
modern dev storybook
```

</CH.Code>

</CH.Spotlight>

If, during development, you encounter a situation where the type definition is not available in real time, at that point.

For `pnpm` projects, `package.json` can be modified as follows.

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

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

For npm and Yarn projects, the values of `types` of `package.json` can only be changed manually in **development phase** and **release phase**.

So why is it possible to reference the product directly?

1. execute `modern build --watch` command before executing `modern dev storybook` command to ensure the existence of project build products.
2. Add processing logic inside Storybook to ensure that the project's product paths can be parsed **according to `package.json`, based on the `compilerOptions.paths` configuration in the `tsconfig.json` file or (in JS projects) directly with the project name as an alias**.

### Referencing component source code

Referencing component source code can be done by means of relative paths to:

```ts ./stories/index.tsx
import { content } from '../src';

const Component = () => <div>this is a Story Component {content}</div>;

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

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

:::tip Why is the source code approach not recommended
Not only is it impossible to verify that the component product is correct using the component source code, **but also some of the configurations supported by the module project for building the product cannot be fully translated into Storybook internal configuration**. If some of the configurations cannot be converted to each other, there will be unintended results during Storybook debugging.

Module Tools is based on esbuild, while Storybook is based on Webpack, and esbuild's configuration is not fully compatible with Webpack.
:::

## Configure Storybook

Storybook is officially configured for projects through a folder called `.storybook`, which contains various configuration files. **In a module project scenario, Storybook configuration files can be added to the `config/storybook` directory of the project.**

For more information on how to use the various Storybook configuration files, see the following links:

- [Configure Storybook](https://storybook.js.org/docs/react/configure/overview)

**But there are some limitations to Storybooking in a module project**:

- It is currently not possible to change the location of the Story file, i.e., you cannot change the `stories` configuration in the `main.js` file.
- Currently you cannot modify Webpack and Babel related configuration, i.e. you cannot modify `webpackFinal` and `babel` configuration in the `main.js` file.

In the future we will consider whether these configurations can be allowed to be modified, but for now we are limiting their use to reduce unpredictable issues.

## Building Storybook Products

In addition to Storybook debugging of components or common modules, you can also perform Storybook build tasks with the following commands.

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

For the `modern build --platform` command you can see.

- [`modern build`](/en/guide/basic/command-preview#modern-build)

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