Publishing Storybook: One main Storybook instance for all projects

This guide extends the Using Storybook in a Nx workspace - Best practices guide. In that guide, we discussed the best practices of using Storybook in a Nx workspace. We explained the main concepts and the mental model of how to best set up Storybook. In this guide, we are going to see how to put that into practice, by looking at a real-world example. We are going to see how you can publish one single Storybook for your workspace.

This case would work if all your projects (applications and libraries) containing stories that you want to use are using the same framework (Angular, React, Vue, etc). The reason is that you will be importing the stories in a central host Storybook's .storybook/main.ts, and we will be using one specific builder to build that Storybook. Storybook does not support mixing frameworks in the same Storybook instance.

Let’s see how we can implement this solution:

Steps

Generate a new library that will host our Storybook instance

According to the framework you are using, use the corresponding generator to generate a new library. Let’s suppose that you are using React and all your stories are using the @storybook/react-vite framework:

Now, you have a new library, which will act as a shell/host for all your stories.

Configure the new library to use Storybook

Now let’s configure our new library to use Storybook, using the @nx/storybook:configuration generator. Run:

This generator will only generate the storybook, build-storybook and test-storybook targets in our new library's project.json (libs/storybook-host/project.json), and also the libs/storybook-host/.storybook folder. This is all we care about. We don’t need any stories in this project, since we will be importing the stories from other projects in our workspace. So, if you want, you can delete the contents of the src/lib folder. You may also delete the lint and test targets in libs/storybook-host/project.json. We will not be needing those.

Import the stories in our library's main.ts

Now it’s time to import the stories of our other projects in our new library's ./storybook/main.ts.

Here is a sample libs/storybook-host/.storybook/main.ts file:

Notice how we only link the stories matching a specific pattern. According to your workspace set-up, you can adjust the pattern, or add more patterns, so that you can match all the stories in all the projects you want.

For example:

Import the stories in tsconfig.storybook.json

Here is a sample libs/storybook-host/tsconfig.storybook.json file:

Notice how in the include array we are specifying the paths to our stories, using the same pattern we used in our .storybook/main.ts.

Serve or build your Storybook

Now you can serve, test or build your Storybook as you would, normally. And then you can publish the bundled app!

or

or

Use cases that apply to this solution

Can be used for:

• Workspaces with multiple apps and libraries, all using a single framework

Ideal for:

• Workspaces with a single app and multiple libraries all using a single framework

Extras - Dependencies

Your new Storybook host, essentially, depends on all the projects from which it is importing stories. This means whenever one of these projects updates a component, or updates a story, our Storybook host would have to rebuild, to reflect these changes. It cannot rely on the cached result. However, Nx does not understand the imports in libs/storybook-host/.storybook/main.ts, and the result is that Nx does not know which projects the Storybook host depends on, based solely on the main.ts imports. The good thing is that there is a solution to this. You can manually add the projects your Storybook host depends on as implicit dependencies in your project’s project.json, in the implicit dependencies array.

For example, libs/storybook-host/project.json: