Storybook Composition Setup

With the release of Storybook 6.0, a new feature has been introduced called Composition, which allows you to combine multiple published Storybooks into one regardless of their frameworks. This is an exciting feature for teams that have multiple Storybooks for different projects using different tech stacks. As my team is also looking into using Storybook Composition, I did some POC work to see how it actually works and I will go through the necessary steps.
I used Amazon S3 to host the Storybooks that were referenced by the composition Storybook.
The term reference Storybooks in this post refers to the individual Storybooks that will be combined into one.
The term composed Storybook in this post refers to the Storybook that is used to combine the reference Storybooks.

Step 1: Upgrade Storybook

Upgrade to the latest Storybook by running the following command in all your reference Storybook repos:

npx sb upgrade

This will upgrade your @storybook/* packages to the latest version.

If you are using yarn, you could also run the following command by replacing framework with whatever storybook framework you are using:

yarn add @storybook/framework --save-dev

More detailed Storybook 6 Migration steps can be found here if you run into issues while upgrading.

Step 2 (if using Amazon S3): Rebuild and Redeploy

If your reference Storybooks are hosted on a CHP level 1 server like www.chromatic.com, you can skip this step.
If your reference Storybooks are hosted on a CHP level 0 server like Amazon S3, you will need to execute this step.

Step 2.1: Rebuild each reference Storybook

Run the following command in the reference Storybook repos to rebuild them with the latest version of Storybook installed in Step 1:

yarn build-storybook

Step 2.2: Generate stories.json file

Run the following command in the reference Storybook repos to generate a file named stories.json:

npx sb extract .out

If you named your build directory differently, replace .out with your build directory name. This command generates a json file that includes a list of all the stories in the reference Storybook that will be used by the composed Storybook. The command creates this file within the build directory ( .out is the default). CHP level 1 servers like chromatic automatically generates this file.

Step 2.3: Redeploy each reference Storybook to S3

Redeploy each reference Storybook to Amazon S3 by uploading the build directory that includes the stories.json file generated in Step 2.2.

Step 3: Create a repo for your composed Storybook

Create a new repository that will reference the external Storybooks and combine them into one Storybook. You will also need to install the latest version of Storybook in this new repo. My package.json looks like this:

{
  "name": "storybook-compositions",
  "version": "1.0.0",
  "description": "Storybook Compositions POC",
  "author": "Do-Yup Lim",
  "private": true,
  "scripts": {
    "storybook": "start-storybook -p 6006",
    "build-storybook": "build-storybook"
  },
  "dependencies": {},
  "devDependencies": {
    "@babel/core": "^7.11.4",
    "@storybook/addon-actions": "^6.0.20",
    "@storybook/addon-essentials": "^6.0.20",
    "@storybook/addon-links": "^6.0.20",
    "@storybook/html": "^6.0.20",
    "babel-loader": "^8.1.0",
    "babel-runtime": "^6.26.0",
    "react-is": "^16.13.1",
    "storybook": "^6.0.20"
  }
}

Step 4: Create/Modify main.js

If you don’t have a main.js file under your .storybook folder, you will need to create one.

Add a refs key to main.js that will contain the information regarding the reference Storybooks. Use the following template to add as many reference Storybooks as needed:

refs: {
  [dummy-key]: {
    title: "Dummy Title",
    url: "dummy.s3-website-us-east-1.amazonaws.com"
  }
}

The title field will be displayed on the composed Storybook site, and the url field must be set to a statically built Storybook.

My main.js looks like the following:

module.exports = {
  "stories": [
    "../stories/**/*.stories.mdx"
    "../stories/**/*.stories.@(js|jsx|ts|tsx)"
  ],
  "addons": [
    "@storybook/addon-links",
    "@storybook/addon-essentials"
  ],
  "refs": {
    story1: {
      title: "Storybook 1",
      url: "http://...s3-website-us-east-1.amazonaws.com"
    },
    story2: {
      title: "Storybook 2",
      url: "http://...s3-website-us-east-1.amazonaws.com"
    }
  }
}

Step 5: Run composed Storybook locally

Run the following command in your composed Storybook repo to run locally and test if the Composition feature works:

yarn storybook

Below is a screenshot of the display panel that shows the list of reference Storybooks that are now combined into one Storybook.

Hope this helps those who are trying out Storybook Compositions for the first time. Feel free to reach out if you have any questions.