[RFC] Proposal to add first-class support for monorepos in a probably easy way

[ernestostifano]

Status: in-review; championed by @shilman

---

Summary

Storybook's current setup/integration strategy (location, dependencies management and configuration interface) is well suited for standard repositories, but not for a monorepo.

Don't get me wrong, it works! And it is flexible enough to be installed in different ways. Still, there are no suggested, officially supported (documented) approaches. As a consequence, some related issues remain unsolved (like #16748) and some questions unanswered (like this).

I would like to share a recent experience I had on a big monorepo and how I solved some of the issues we encountered, with minimum impact.

Problem Statement

• The most common way to integrate Storybook is to put it in the root of your project under a directory called .storybook.

• Dependencies are installed in the root's package.json file.

• At this point, Storybook behaves really well in a monorepo, as long as you configure it to find your stories across different packages/locations.

• Integration with other common tools and technologies is also relatively good (ESLint, Prettier, TypeScript, Yarn 2, Yarn PnP, Yarn Zero-Installs, Babel, GitHub Actions, etc.)

• Things started to go downside when we faced the need to add some decorators to insert various providers to our stories.

• Some providers come from our own packages and some are even wrappers of other providers coming from external libraries (JSS, Redux, etc.).

• If a story placed in package B imports a context from package A (like import {MyContext} from '@scope/package-a') and a decorator imports the same context with a relative import (like import {MyContext} from '../../packages/package-a'), even if the resolved file is the same, both contexts will be bundled separately, and the story will not work (provider and consumer will not recognise each other).

• The above is only a fairly simple example of a wide range of issues that could arise because, in this configuration, Storybook is not inserted into the monorepo's packages loop.

• The more your decorators rely on external dependencies or in your own packages, the worst it can get.

• Another potential issue becomes relevant if your monorepo contains more than one framework (for example React and Angular).

• Also, imagine that you have all your tools configured for your packages in a specific location and with a specific naming convention. Having Storybook outside of that structure and following different conventions forces you to write additional overrides and to take that into consideration when configuring tools like EsLint or even TypeScript.

• From all of these, objectively speaking, only the dependencies and the multiple frameworks situations are to be considered particularly important.

• The good news are that probably all of these can be addressed at once.

Non-goals

N/A.

Implementation

Note: Everything was done using Storybook v7.

Once we identified the above issues as the source of our problems (especially the dependencies one), the first solution was to simply add our .storybook directory as a package of our monorepo. Something like this:

{
    "workspaces": {
        "packages": [
            "packages/**",
            ".storybook"
        ]
    }
}

Then, we immediately added a specific package.json file inside the .storybook directory and moved all Storybook's dependencies into it. We also added some of our own internal packages as dependencies and this immediately fixed our problem. So also the issue (#16748) and question linked above. Great!

The only caveat found so far is that for some strange reason "@storybook/react-webpack5" needs to remain in the root's package.json file, while all other dependencies can be moved without issues (this is a first symptom of Storybook relying on being in the root of a project, which in any case, IMHO, should be avoided, especially if it does not take too much to do).

Beside that, we also added its own tsconfig.json and .eslintrc.js files, both extending the ones in the root, just like any other package. The integration is starting to feel more sound and monorepo friendly.

At this point, since everything went fairly well, we wanted to test our luck by moving Storybook (which is now a package) into the packages directory. The objective was to stick to our own conventions and avoid having to write especial overrides when configuring our other tools (as explained above).

So, we wrapped the .storybook directory inside another directory called something like react-stories and moved it into the packages directory. Also, package relative configuration files (like the package.json) were moved out from the .storybook directory. Finally, we renamed the .storybook directory into src. It ended being something like this:

react-stories
├── .babelrc.js
├── .eslintrc.js
├── CHANGELOG.MD
├── package.json
├── src
│   ├── addons
│   ├── components
│   ├── decorators
│   ├── defines
│   ├── main.ts
│   ├── preview.ts
│   ├── themes.ts
│   └── utils
└── tsconfig.json

This turned to be just great... All the issues described above were gone! Now Storybook has its own reserved package, tracking its own dependencies, it has access to the monorepo's packages loop, so no issues with contexts nor anything related to double builded modules. The package contains its own scripts for dev and build, no special rules, regarding other tools configuration, because the structure is the same as for all other packages and finally, if there was a need to support multiple frameworks, we could just add a new package with a completely separate Storybook. Also, the Storybook Static App gets builded inside its own package and in a more sound way.

Unfortunately, this is not documented anywhere (not that I could find). But it would be great to officially support this pattern... because it really seems like first-class support for monorepos... could be advertised as that!

Benefits:

• Allows Storybook to hook into the monorepo's package system (especially important if using Yarn PnP, thus avoiding issues like the ones explained above about separately building the same module. Also, dependencies on other packages can be tracked better.
• Avoids pollution of the root's package.json file which usually contains only development dependencies and scripts.
• Makes the build of the Storybook Static App more sound, as relative package.json will only contain needed dependencies, well distributed between production and development ones.
• Allows having multiple Storybook instances/integration, cleanly supporting multiple frameworks in the same monorepo.
• No special configuration for .ignore files and tooling required (since Storybook could be installed following already existent project conventions in terms of file names, locations, etc.).
• There is little effort required to officialise the approach/pattern and ensure its stability.

Prior Art

N/A.

Deliverables

N/A.

Risks

N/A.

Unresolved Questions

However, the following minor doubts/issues remain:

• The approach is not documented, thus I'm worried it could break in the future.
• With the standard configuration, Storybook was not finding the babel.config.js file in the root (as it should, per Babel's documentation). We had to add a local .babelrc.js file in the package with something like:

{
  "extends": "../../babel.confg.js"
}

Which I don't really like.

• "@storybook/react-webpack5" is still required to be installed in the root (the only one).
• With the standard configuration, despite stories were being loaded as expected (including stories in other packages), they were not transpiled with Babel (so unexpected token errors were received because of TypeScript). This was fixed by adding configFile option (also rootMode works) in the babel-loader configuration (using webpackFinal property in main.ts file). Strangely it also works if either of these options is injected in the Babel configuration using babel property in main.ts file.
• In version 7.0.7, if the .babelrc.js file was present, the Storybook's manager was being transpiled using our Babel configuration (double log from our config file). If we removed the file, only the preview (and stories) were transpiled with our Babel configuration. After upgrading to version 7.0.9 it does not matter the presence of the file, the manager does not use our configuration.
• Finally, since many commands assume that the Storybook source directory is called .storybook, to avoid passing the -c option each time, it would be cool to have a storybook.config.js file (and/or similar) to contain the source path like:

module.exports = {
  src: "./src"
}

(maybe some additional options could by added/migrated in the future)

Alternatives considered / Abandoned Ideas

N/A.

[shilman]

Thanks so much for making this proposal! Monorepos are definitely one of the pain points for Storybook, especially since there are so many different monorepo setups to consider.

I like the idea of better supporting a standalone Storybook package in a monorepo. Historically we've had various problems where Storybook's dependencies have conflicted with user dependencies, and this direction could potentially address that.

To help make this proposal more concrete, could you create a sample monorepo using the new proposed structure (dummy packages/components are fine) and link it in the RFC?

[thedaviddias]

@ernestostifano any way to have this sample monorepo? I'm really really interested to see this working.

[sgoodrow-zymergen]

Also interested in seeing an example.

[nareshbhatia]

I have linked to an example in my comment: #22521 (comment)

[JReinhold]

I love this, I had the exact same idea today, that we should explore what it would take to make it possible for Storybook to be its separate package in a monorepo, to cleanly separate it from the rest.

[ernestostifano]

Hi guys @shilman , @JReinhold, thanks for your feedback. I am glad this is of interest. Will try to create the repo during this week so maybe we can start working on it! Will keep you posted.

[shilman]

The biggest issue that I see with this issue is that Storybook and its associated tooling assumes access to your original component source code, e.g. your stories should import your component from ./Button instead of importing from package-name/Button.

When you import from a package, you're typically getting the transpiled code which often strips out:

• code comments
• display names
• propTypes
• etc.

This would make it hard to auto-generate docs/controls from your component's API. There are aspects of supporting this pattern that we might be able to fix with improvements/tweaks to Storybook, but I'm not sure how we'd get around this one.

[ernestostifano]

Hi @shilman, stopped by to answer on the fly (still haven't had the chance to create that repo yet).

In our case we do not have that issue at all, because all stories still live in their respective packages, thus importing the respective components directly (not as external modules).

Our main.ts file contains the following entry:

const config: StorybookConfig = {
    // ...
    stories: [
        {
            directory: '../../',
            files: '*/src/**/*.stories.tsx'
        }
    ],
    // ...
};

Which catches all stories in all packages (so also outside of the Storybook's package).

This pattern needs to be validated, but it is currently working. Would not harm to support classic include and exclude properties there. Thinking of possibly having different instances of Storybook (different Storybook packages) targeting different stories.

As a matter of facts, our Storybook package does not contain any story at this time and I never thought about your scenario, which I think would be great! Having some higher level stories declared there, with access to different components in different packages... Or probably someone just wants to have all their stories in a single package. I am interested!

Anyway, I understand your concern.

Based on the assumption that everything that gets imported from a package should be exported from its entry point, what if we resolved the module identifier to the root of the corresponding package? At this point we would only need some indication from the user (via configuration?) to reach the source's entry point and then get the relative path to it in order to replace it in the original import statement. This would give us access to the source code of the component.

Just thinking out loud here, will continue to think about it.

If it helps, we used Webpack's Alias feature to remap all imports from the built code to the actual source code. This way we get Hot Module Replacement everywhere (even for stories of components that import code from other packages). No perceivable performance impact.

[briavicenti]

I'm trying to set up a monorepo exactly as you describe, @ernestostifano, but I'm seeing issues with docgen working when stories live in their respective component packages as opposed to the storybook package. I would really appreciate seeing an example monorepo setup to try and troubleshoot against!

[ricovitch]

I'm also very interested in being able to separate storybook(s) from component source code in a monorepo.

Here is our context in Airbus Design System

• monorepo with css, react and angular libraries, all three using storybook
• managing packages dependencies in general is a difficult task
• we make this task even more difficult by supporting old versions of angular and react
• updating storybook to latests releases is better done at the same time for all 3 packages, but that usually has big impacts on the library dependencies itself (typescript, webpack, etc.)

To be more concrete, let's say we need to support angular up to v11, then we need to share dependencies of angular11 with storybook in a single package.json file.

With this context, moving storybooks to separate packages in the monorepo looked to be an escape hatch, allowing us to use latest storybook releases without worrying about conflicts with the libraries dependencies, that we can manage independently.

We made an attempt few months ago, with storybook v6.5 at this time.
In our case we wrote stories in the storybook packages directly, and it looked to work fine for css and react storybooks.
We only had issues with angular, and went to the conclusion that it was due to old angular version and missing ivy compilation.

We were also a bit confused by the fact that storybook documentation clearly does not recommend doing this kind of separation.

[ricovitch]

UPDATE :
since june we updated our react and angular libraries to follow LTS policies from angular and react teams.
So we dropped support for old versions of angular and react in the context of a major release of our design system.
This allowed us to update storybook in all packages. We migrated to 6.5 as a first step, and it went well.
We should be able to update to storybook 7 in a second step, without big dependencies issues. It's more about taking the time to follow the migration path from 6 to 7 and adopt the new best practices.

On the principle, we are still interested on being able to separate storybooks from code, but that is less critical for us now.

[nerdyman]

I've been able to get docgen working in my monorepo by specifying the the path to my lib source directory in the Storybook docgen options.

My project is structured like:

• /src - lib source
• /docs/storybook - Isolated Storybook install

// docs/storybook/.storybook/main.ts
const config: StorybookConfig = {
 typescript: {
    reactDocgenTypescriptOptions: {
      include: ['../../src/**/*'],
    },
  },
};

export default config;

I haven't been able to get the test-runner code coverage working however. I can't get it to include files from outside of the Storybook root directory.

[nareshbhatia]

@ernestostifano, thank you for starting this discussion.

We have been playing with Storybook configuration for monorepos in our open source project Code Shaper for quite sometime. The goal of this project is to encapsulate best practices such as Storybook, Testing, Linting in customizable templates so that developers can create new projects conforming to team standards very easily.

We started off with exactly your approach – a separate Turborepo workspace for Storybook and wiring it up to all the apps and component libraries in the monorepo. You can see an example here which has a mix of Vite & Next.js apps as well as a common component library. However, the process of adding dependencies to more and more workspaces becomes very cumbersome, especially with different apps having different wrapper & mocking requirements (REST vs. GraphQL, ...).

Given this, we are contemplating to move to one storybook per app approach. This would allow storybooks to be configured nicely to the app requirements (e.g. Webpack vs Vite), but still allow inclusion of component libraries from other workspaces. This approach is working quite well, except for one minor issue (see this discussion).

In any case, this is an important piece of the Storybook puzzle that we should try to nailed down.

[nareshbhatia]

Following up on my comment above, we concluded that one storybook per app approach is much cleaner than one storybook per repo approach. The main reason for this is that storybook usually requires the same configuration as the app, e.g. package dependencies, Next vs Vite app, mock service worker configuration, etc. Having them in different workspaces requires duplication of configuration and somewhat awkward ways of making Storybook work. Note that if the repo contains only component libraries, we create a dummy app just to host Storybook. So far this approach is working very well for us. Please see this example where we have configured one storybook for the movie-magic-react app + it also pulls in components from the ui-lib component library.

[LukasBombach]

This is our project structure

monorepo-root
├── apps
│   ├── app-1
│   ├── app-2
│   ├── storybook
├── packages
│   ├── ui-library
│   ├── ...

the way we think about our repo and storybook is that we have packages that do nothing, and a apps that can be started and or deployed. In that way, storybook is one of the apps in our repo while our ui-library just lies there until used in some way.

Also, our *.stories.tsx files are inside of the ui-library to co-locate components and their stories.

I wonder how you feel about that way of thinking in regards to use-cases in the scope of this PR

[aaronadamsCA]

I'm surprised nobody seems to have mentioned Storybook composition yet. I think it already solves most of the problems this RFC identifies, including decorators and multiple frameworks; and without the unresolved questions it raises.

I think of stories the same way I think of tests. I don't particularly want to separate either from their source code! In our front end packages, every component lives together with its stories and tests, all in one place.

We have one Storybook per app package and one Storybook per library package, and then we use composition:

• app-1 Storybook composes package-a Storybook and package-b Storybook.
• app-2 Storybook composes package-a Storybook and package-c Storybook.
• etc.

This seems to work regardless of the differences between packages. Even HMR works well!

Our biggest current pain points are:

• During dev we need to run each Storybook instance manually, in the right order, and coordinate port numbers between packages.
  • Thankfully composition degrades gracefully, so we only need to follow these extra steps when we actually need the child stories to appear.
• We don't even bother composing builds yet. In particular, coordinating ephemeral deploy preview URLs looks like it would be painful.

What could help with this is some kind of instance orchestration in the Storybook CLI. If a parent Storybook could compose a bunch of children, and the whole thing could storybook dev or storybook build in one shot—that would be amazing.

I have no idea how this would work under the hood, but maybe somebody else would know of some prior art in the ecosystem for this kind of approach.

[JReinhold]

I think you're on the right path here (and most comments above here to a degree), and following the workflow originally intended by the Storybook team but never fully communicated.

• One Storybook per app/lib - not per repo. This allows the Storybook to match the tech stack of each app/lib
• Composed together using Composition for a single Storybook.

On a technical level, Storybook can be considered similar to unit tests that must live and run next to the source for them to work best. But as we've heard countless times, from a conceptual level Storybook is often considered its own separate app, hence the desire to have one per repo.

There are already a handful of good monorepo orchestration tools out there (Turborepo, NX, Moonrepo, Rush, Bazel, etc.) and I don't think Storybook should attempt to do what they do as it's a very hard problem. Instead we should provide docs and recipes for how to work with them and combine Composition with monorepo orchestration.

I do wonder however if there's anything else we can do to improve the Composition functionality besides docs/guides/recipes.