Configuring Storybook on Nx

Best practices

Read our Using Storybook in a Nx workspace - Best practices guide!

Starting with version 15.7, Nx is no longer generating a root Storybook directory and shared root Storybook configurations. Instead, it is only generating a Storybook configuration for each project in your workspace. You may still manually create a root Storybook configuration file, if it is needed for your use case.

You can read all about creating and using a root Storybook configuration in our guide How to configure Webpack and Vite for Storybook.

This change means that each of your projects that has Storybook configured has only one, project-level, project-specific .storybook/main.js|ts file that it relies on, without importing settings from external files. This simplifies the configuration process, makes it easier for the user to understand the configuration that each project is using, and also makes it easier to maintain, relying on automatic migration scripts, for example.

This does not change much for the user, as the configuration process is still the same, and you may still manually create a root Storybook configuration file, if it is needed for your use case.

Project-specific configuration

You will notice that all project-specific configuration files contain the @storybook/addon-essentials addon, which is the shared setting among projects. Other than that, depending on the project type, the settings differ in regards to the builder used, the stories import glob pattern, and, in the case of projects using Vite, the path to the vite.config.ts file or the root of the project, for correct path resolution. All these are automatically generated by Nx, so you don't have to worry about them.

Root Storybook configuration

If you need to create a root Storybook configuration file, you can do so by creating a .storybook/main.js|ts file in your workspace root. Then, you may import this file in your project-level Storybook configuration files. However, this is rarely needed in most cases, since most settings for builders like Webpack and Vite, for example, are already built-in into the Storybook builders.

Moving away from the root Storybook configuration

If you are using nx migrate and you migrate to version 15.7 or later, Nx will try to automatically migrate your root Storybook configuration to the project-level Storybook configuration files. However, if you are not using nx migrate, you can still manually migrate your root Storybook configuration to the project-level Storybook configuration files.

If you still want to keep your root Storybook configuration files, and if you have settings there that Nx cannot move to the project-level Storybook configuration files, Nx will leave your files untouched. You may keep your root Storybook configuration files, and Nx will still work as it did.

The Nx migrator will do the following:

  1. It will add the @storybook/addon-essentials addon to all project-level Storybook configuration files.
  2. It will remove the @storybook/addon-essentials addon from the root Storybook configuration file.
  3. If the addons array in the root Storybook configuration file is empty after removing the @storybook/addon-essentials addon, it will remove the addons array from the root Storybook configuration file.
  4. If the stories array in the root Storybook configuration file is empty, it will remove the stories array from the root Storybook configuration file.
  5. If the root .storybook/main.js|ts configuration file is empty after removing the addons and stories arrays, it will remove the root .storybook/main.js|ts Storybook configuration file.

In all the other cases, Nx will not interfere with your Storybook setup.

Read our guides for Configuring Storybook

You can read all our guides for configuring Storybook in our Storybook documents page.

Please also make sure to read our Using Storybook in a Nx workspace - Best practices guide, where you can find some best practices for using Storybook in a Nx workspace.