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

[Mrtly]

have you found a solution to the coverage issue?

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

[cezudas]

@nareshbhatia I am sorry I can't find the ui-lib project anymore in the repo you mentioned, the link does not work.

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

[LarsPede]

I'm about to get into the exact same problem/structure that @aaronadamsCA mentions... I'm setting up storybook as a separate app because "apps" in our repo is "hosted entities". The need for manually starting several storybook instances is the only things that is currently keeping me from using composition.

I think an improvement that would allow composition to work beautifully in monorepos would be to allow the option of referencing another .storybook/main.ts folder and pull the storybook instance from there. Storybook would only have one entry point but would be composed of multiple .storybook references.

[aaronadamsCA]

Yeah, I'm just not sure outside tools are a great solution here.

• Needing to run/orchestrate multiple instances of Storybook is far from ideal and doesn't scale well.
• Needing to tell each parent Storybook the URL of each child Storybook is a real pain:
  1. To develop, tell each parent Storybook the URL of each child Storybook. 🫤
  2. To build and deploy, set up hosting for every child Storybook, and tell each parent Storybook that URL, too. 😬
  3. To deploy branch previews, figure out how to pass dynamically generated child URLs to each parent Storybook. 😫

I think the better solution is a new interface for Storybook references. The HTTP interface is nice, but IMO it's best suited to pointing to external references. For internal ones, @LarsPede's suggestion that we be able to reference a .storybook/ directory (or even a named package) feels much more natural.

It's also the most similar to how modern app monorepos like ours already work in other respects. We no longer have to orchestrate building child packages to be consumed by parents; today's tooling works just fine across local package boundaries. Subpath imports and exports, HMR, these days everything "just works."

I think it would be great if Storybook references could work the same way.

[shilman]

Thanks @LarsPede @aaronadamsCA !! I've been thinking in the same direction and there's a decent chance we'll do a project about this. Do you have a proposal for what the configuration API would look like?

[aaronadamsCA]

@shilman Maybe something like this?

packages/child-package/.storybook/main.ts

import { createConfig } from "storybook";

export default createConfig({
  framework: {
    name: "@storybook/react-vite",
    options: {
      builder: {
        viteConfigPath: ".storybook/vite.config.ts",
      },
    },
  },
  stories: ["../src"],
});

packages/parent-package/.storybook/main.ts

import { createConfig } from "storybook";

import childPackage from "@mymonorepo/child-package";

export default createConfig({
  framework: {
    name: "@storybook/react-vite",
    options: {
      builder: {
        viteConfigPath: ".storybook/vite.config.ts",
      },
    },
  },
  stories: ["../app"],
  refs: {
    "child-package": childPackage,
  },
});

createConfig() would be an identity function with one extra trick—adding a property with the absolute path to the config file. Now you could pass this POJO to another config as a reference, and Storybook would still know how to calculate its relative paths, without concerning itself with how you are passing that object around between packages.

To correctly resolve dependencies in this scenario, I imagine you might need to follow ESLint's lead and graduate from strings to module imports when configuring the framework and addons.

I'm not sure how well this would work, but hopefully it can spark some ideas!

[shilman]

@aaronadamsCA I love this. The createConfig and replacing strings with imports in our config files is something we've been talking about for awhile now. Applying these ideas to make composition more ergonomic is fantastic. If you squint a little bit, it also resembles what we did with CSF/MDX in 7.0.

It might take some time to make this all happen cleanly. Our users hate change, so we always end up bending over backwards to try to make the changes as smooth as possible. But this feels like a fantastic design, and something that we should be able to make happen. Thanks so much and let us know if you'd be at all interested in helping build it.

Cc @kasperpeulen @JReinhold @ndelangen @tmeasday

[Shusanta]

👋 currently working in a setup where there is a storybook package with all of our stories but cannot get autodocs working. We just did also did some work to not allow direct imports in package/src/etc instead of just from package. Anyone able to fix/bypass this?

[shilman]

Can you explain more about your setup?

[Gawdfrey]

Proably a bit unrelated, but I had success using the wait-on approach, described here. Primarily applies to turborepo.

Just have a wait-on scripts that waits on the port to open up, then run the primary storybook instance

[Badisi]

In case anyone is interested, I successfully managed to get Storybook working as a separate project in a monorepo.

Relevant parts:

• root package.json
• angular.json
• story-book project

Remaining issue:

• Storybook commands have to be executed from the root directory of the monorepo (otherwise dependencies could not be found)
  But this can be easily worked out like this: package.json#L4

[sergesemashko]

In case someone is looking for a comprehensive monorepo setup of storybook - here is good example https://github.com/Financial-Times/origami.

I ended up implementing similar setup in my workplace for storybook thankfully to this repo.

P.S. they addressed an interesting problem of navigating between different versions of the same component by building custom viewer engine. I didn't attempt to mimic it, but it might be a useful reference example.

[YoungElPaso]

This also seems like a great example project. Quite straightforward with some nice docs/examples:

https://github.com/thepixelperfectdev/monorepo-setup-starter

[anisjonischkeit]

Some anecdotal experience around this:

At my organisation I recently introduced storybook to two of our projects, both projects are monorepos.

Project 1

In the first project, I added it using an approach similar to what is described here (we have a /storybook folder in which storybook was created using the storybook cli). Directory structure looks like this:

├── packages
│   ├── pkg-1
│   │   ├── package.json
│   │   └── src
│   └── pkg-2
│       ├── package.json
│       └── src
└── storybook
    ├── .storybook
    ├── package.json
    └── src
        ├── extra-resources
        ├── foundations
        └── guides

We got most things working using this approach, but it felt a bit like pulling teeth getting everything working. We wanted the stories to live inline with the components in our packages, and getting everything to resolve properly was a pretty big ordeal to figure out. Additionally, we were able to use the react-typescript-docgen package, but only if we were building storybook using webpack.

Project 2

In the second project, we started with the same approach as above, but this time it was much more important to get vite working. Hot reload times in that project using webpack were unbearably slow and vite was an answer to that problem. I could get vite to work, but again with subpar doc generation (no react-docgen-typescript) and a bunch of stuffing around with tsconfigs/workspaces/lerna/etc. Eventually I gave up on separating out storybook into its own package, moving it to the root of the monorepo, and I had everything working within an hour or so.

Not sure how useful those anecdotal stories are, but at this stage we're actually leaning more in favour of "storybook is just a build tool for the entire repo". We probably had an easier time with it being at the root of the project because we only have React libraries, but it definitely felt easier. In the first approach we also still ended up with @storybook/blocks and @storybook/react in the root package.json as it would be used by all packages in the monorepo

[yuri-scarbaci-lenio]

sharing some anecdotal experience around this too

In our design system, we opted to fully decouple Storybook from our monorepo, treating Storybook as an independent entity with its own content. We implemented this approach back around Storybook version 5.

Our setup looks like this:

├── packages
│   ├── pkg-1
│   │   └── // ... our monorepo raw code and build steps
│   └── pkg-2
│       └── // ... our monorepo raw code and build steps
└── environments
    ├── storybook
    │   ├── package.json
    │   ├── .storybook
    │   ├── ... Storybook-specific files and configurations
    │   └── stories
    │         ├── pkg-1
    │         │     ├── Basic.tsx  // this includes 0 storybook propetary syntax, it's completely agnostic and reusable in other portals
    │         │     ├── [...our "plain" example implementations]
    │         │     └── index.stories.tsx  // CSF format, imports and re-exports stories; only these files are loaded as stories
    │         ├── pkg-2
    │         │     ├── Basic.tsx
    │         │     ├── [...our "plain" example impelementations]
    │         │     └── index.stories.tsx
    │         └── [... other packages]
    └── next.js   // Tests components against different setups

We’ve built custom, ad-hoc addons tailored to our needs. This approach was necessary since Storybook 5 lacked some features we required at the time. As a result, I can't speak much about how Storybook 8's built-in features would integrate with this setup. However, this structure fully decouples Storybook from our monorepo, allowing us to manage separate versions, tools, and build steps. Essentially, Storybook is just another consumer of our monorepo components—like any other application (e.g., a Next.js demo app).

To manage dependencies, we leverage pnpm's workspace:* feature in the environments/storybook/package.json. This setup meets our needs perfectly.

Although there’s some redundancy in the folder naming convention, this "AHA" approach brings more clarity and value to us than a strict "DRY" setup would. We prefer to keep our monorepo components completely agnostic and self-sufficient. Embedding .stories.tsx files directly in our raw code feels like a counter-pattern for our objectives, as it ties component logic too closely to Storybook-specific concerns. This decoupled approach keeps our components scoped, flexible, and adaptable for different environments.

(To each their own, of course, but this works well for us.)

[yuri-scarbaci-lenio]

this is a kind of reproduction in stackblitz of our setup
(in the stackblitz I could not use nx because nx doesn't support linux64 distro used by stackblitz so I instead used pnpm --filter to run the command)