Storybook Composition - loading a prebuilt storybook into yours

[ndelangen]

Storybook is used by teams, and it's actually quite common for multiple teams to work on their own isolated features, possibly in their own storybook. But it's also common these teams will share components between them.

In fact a very common scenario is that you're using some open source components, maybe a component library. They are using storybook, you are using storybook. But if you want to see their components -and the documentation that come with it- you have to go to their website/storybook or write stories for components that aren't yours.

This is wasting time. Storybook should have a mechanism to deal with this.

Presenting: storybook inception!

// main.js
module.exports = {
  stories: [`${__dirname}/stories/*.*`],
  addons: [
    '@storybook/addon-roundtrip/register',
    '@storybook/addon-parameter/register',
    '@storybook/addon-preview-wrapper/register',
  ],
  refs: {
    inception: 'https://storybookjs-next.now.sh/dev-kits/iframe.html',
  },
};

The new refs lists all external (pre-build) storybooks you want storybook to load.

The storybook is loaded, and the stories defined in both will appear in the navigator.

Here's one of the challenges I faced: Stories might have the same name, and thus overwrite each other.
The default way storybook now deals with this is by prefixing all stories's kind with the id of the ref that loaded it.

There's a way to tweak this behaviour, because I expect the consumers will want some control over where included stories are placed. Here's how you do it:

// manager.js
import { addons } from '@storybook/addons';

addons.setConfig({
  mapper: (refObject, storyObject) => {
    // return a storyObject, perhaps with a kind you customized
    return storyObject;
  },
});

If you return null then that story will be ignored, and not shown in the navigator.

---

The stories from 1 ref and another are completely isolated. Storybook will actually not merge them together, in fact storybook will load the actual iframes as specified in the ref, and 'juggle' multiple iframes and show the correct iframe for the currently selected story,

Currently this process isn't optimised, which means all refs are loaded from the start.
Once storybook has a way to pull the list of stories statically, we can lazy-load the iframe.

---

todo still

• expandable refs
• test auth flow
• documentation
• extract command with lazy puppeteer install
• preset to auto-load refs from dependencies

[vercel]

This pull request is being automatically deployed with ZEIT Now (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://zeit.co/storybook/monorepo/3o33u9dzy
✅ Preview: https://monorepo-git-core-ingestion.storybook.now.sh

[shilman]

Hey @ndelangen, would love to add a more "convention over configuration" API. Let's discuss offline before merging. In the meantime will test out what you currently have!

[ndelangen]

@shilman let's talk about this in the near future.

[mrmckeb]

This looks really cool @ndelangen - it's a huge PR, but I get that a lot of this work wouldn't make sense in isolation.

I can already see a lot of use-cases for this, from versioning through to framework mixing, and of course importing Storybooks from other sources (such as consumed libraries).

@tmeasday, perhaps it's best if we get this in now, then create seperate PR(s) for authentication and UI updates? I think the sooner we get people playing with this, the better. I also feel like there will be quite a few tweaks and changes based on community feedback.

[tmeasday]

@tmeasday, perhaps it's best if we get this in now, then create seperate PR(s) for authentication and UI updates? I think the sooner we get people playing with this, the better. I also feel like there will be quite a few tweaks and changes based on community feedback.

Yeah, I'm down with that. There were a few outstanding things on the PR, I'm not sure if @ndelangen has addressed them yet? (It's such a beast it's hard to get a quick overview).

In any case it's minor stuff now.

[mrmckeb]

It looked like most had been addressed when I was reviewing yesterday. Norbert walked me through it which helped. @ndelangen was there anything else?