[RFC] Deprecate StoriesOf

[shilman]

Status: in-review; championed by @shilman

Summary

We propose deprecating the StoriesOf API in Storybook 7.1 and removing it completely in 8.0.

We propose three migration paths for existing StoriesOf users:

1. Convert your stories to CSF using the storiesof-to-csf codemod or manually.
2. Use an officially-supported Indexer API to dynamically generate CSF stories. This RFC includes a proof of concept that demonstrates this in action. The indexer API will be available in 7.x in advance of StoriesOf removal.
3. Capture programmatically-generated Variants WITHIN a story, rather than generating multiple stories. There are a few existing community addons for this, and we are considering official support for this in the future, but probably after 8.0 has already been released.

Problem Statement

StoriesOf is the original API for creating stories in Storybook. In Storybook 5.2 (2019) we replaced it with Component Story Format (CSF), which is a simpler, portable, and more performant successor. We provided a utility codemod storiesof-to-csf to help users create most StoriesOf stories to CSF.

// storiesOf example
import { storiesOf } from '@storybook/react';

storiesOf('Button')
  .add('Primary', () => <Button primary />)
  .add('Secondary', () => <Button />);

// equivalent CSF
export default { title: 'Button' };
export const Primary = () => <Button primary />;
export const Secondary = () => <Button />;

We continued to support StoriesOf for a few reasons:

1. To give time for CSF to mature,
2. To give time for StoriesOf users (all users in 2019) to migrate,
3. To propose a CSF-based alternative to dynamically create stories in code.

Four years has been ample time for points (1) and (2). Today, the vast majority of Storybooks use CSF and there are millions of CSF stories in the wild. This RFC focuses on point (3).

But before we jump into that, why is supporting StoriesOf such a problem?

In Storybook 7 we introduced a performance-oriented on-demand architecture called Story Store v7 (SSv7). Unfortunately, SSv7 requires that we are able to statically analyze stories, which is not possible using the StoriesOf API. Therefore, we introduced a legacy mode called Story Store v6 (SSv6) to support StoriesOf.

1. Maintenance. SSv6 is a separate codepath that adds a lot of complexity to Storybook and has to be separately tested and maintained.
2. Speed. SSv6 is multiple times slower to start in dev mode and load in built storybooks.
3. Compatibility. SSv6 doesn’t work with Test Runner and other upcoming features.

We want to provide a path forward for StoriesOf users so that we can deprecate StoriesOf in 7.1 and remove it in 8.0. We’ve isolated two main use cases that we’d like to support better in CSF:

1. Fixture data. Some users have fixture data in JSON, YAML, databases, or API servers and want to automatically turn this data into stories.
2. Programmatic generation. Some users want to programmatically generate stories, for example to test all combinations of a set of component inputs.

Therefore, this RFC focuses on how to achieve these two use cases in a CSF/SSv7 compatible way. We hope this gives existing StoriesOf users a chance to review our approach and give feedback if (1) the proposed solutions aren't suitable, (2) there are other use cases we should consider, (3) there are other approaches we should consider taking.

Non-goals

1. Feature parity. We are not trying to provide feature parity with StoriesOf. We just want to solve the problems that it solves.
2. Automatic upgrade. We are NOT trying to provide any kind of automated upgrade process for StoriesOf users. The proposals here may require substantially reworking your StoriesOf stories. For an automated approach see our existing storiesof-to-csf migration, which works for many StoriesOf files.
3. Personal preference. We are not concerned with personal preference around ergonomics. For example, when we introduced CSF, some users complained that they missed being able to define all their stories in a single file, whereas CSF requires that you split each component’s stories into a separate file. We’re open to all feedback about any solution we propose, but the main goal is to support the use cases listed above while achieving SSv7 compatibility.

Implementation

We propose three paths forward for existing StoriesOf users:

1. CSF. Convert your stories to CSF using the storiesof-to-csf codemod or manually.
2. Indexer API. Use an officially-supported “Indexer API” to dynamically generate CSF stories. This RFC includes a proof of concept that demonstrates this in action. The indexer API will be available in 7.x in advance of the StoriesOf removal.
3. Variants. Capture programmatically-generated Variants WITHIN a story, rather than generating multiple stories. There are a few existing community addons for this, and we also plan to add official support for this in the future, but probably after 8.0 has already been released.

CSF

Users can convert their stories to CSF using the storiesof-to-csf codemod or manually. Given that CSF is 4 years old already, and that we’ve announced the future deprecation of storiesOf shortly after we released it, we assume that everybody who could take this route has already done so. Therefore, we won’t discuss it further here, but are including for completeness.

Indexer API

The Indexer API is a way to programmatically tell Storybook about the existence of stories that can be loaded as CSF. Users or addons can register “indexers” which run in Node and run over files in the user’s stories glob in main.js. The tricky bit is that when that file gets loaded by Webpack or Vite, it must also be loadable as CSF. This has already been applied to alternative syntaxes for stories, such as a “Svelte-native” story format. The Indexer API is already described in a separate RFC in much more detail.

How is this applicable to StoriesOf users? We’ve put together a dynamic stories proof of concept using the Indexer AP:

• Based on fixture data
• For combinatorial stories

Please check out the demo to see how it works. It is implemented in a small amount of code on top of the Indexer API:

Note that while we plan to support the Indexer API, we have not released an officially supported package for either of these use cases. The combination of the Indexer API and Storybook’s addon system mean that anybody from the community could create an addon that enables this kind of programmatic story generation.

Variants

The second approach is to capture multiple variants WITHIN a single story. Consider the following storiesOf example:

const stories = storiesOf('Button');
const propsCombos = generate(); // some code that generates combinations
propsCombos.forEach(props => stories.add(() => <Button {...props } />;

This could be rewritten inside a CSF story:

export default { title: 'Button' };
export const Combos = () => {
  const propsCombos = generate(); // same as above
  <Grid>{propsCombos.map(props => <Button {...props} />)}</Grid>
};

There are existing community variants addons that are usable today.

Variants addon

Permutation table addon

We are also considering building this into an official Storybook feature at some point in the future. If we do this, we’d also provide stylized ways of authoring variants and Variants support across various tooling that we provide.

Prior Art

Mostly listed above

Deliverables

• An officially supported Indexer API
• A recipes for how to use the Indexer API for fixture-based stories & combinatorial stories
• Deprecate the storiesOf API in 7.x
• Remove the storiesOf API and StoryStore v6 support in 8.0
• Migration docs based on this proposal or an evolution

Risks

1. Unhappy storiesOf users. The biggest risk is that there are StoriesOf use cases that we have not considered here, or “dealbreaker” limitations of the approach that we’re unaware of, and that we cannot find a suitable replacement for StoriesOf in time to remove support in 8.0.
2. Late variants support. Storybook has a huge surface area, tons of users, and a long backlog of bugs and feature requests to work through. It’s a risk that don’t implement official variants support in time to help out StoriesOf users before we remove it from Storybook.

Unresolved Questions

• Is this suitable for StoriesOf users?
• Are there use cases for dynamic stories that are not considered here?
• Are there other approaches that we should consider?

Alternatives considered / Abandoned Ideas

No response

[thibaudcolas]

Great to see this 😄 I’ve been putting off keeping up with Storybook updates due to the storiesOf uncertainty, this adds a lot of clarity. There’s clear overlap between this and #23176 at least for my use cases, so I’ve commented there first.

Compatibility. SSv6 doesn’t work with Test Runner and other upcoming features.

I think it’s worth mentioning that from the perspective of a storiesOf user for dynamic stories generation, this isn’t really an issue. It’s completely understandable that stories generated at runtime might not have the same support for features relying on static analysis. I appreciate the fragmentation / limitation of capabilities isn’t desirable from a maintainers’ perspective but personally as a user I’d happily make that trade if it allows me to use Storybook’s core feature of "display a component with specific data in isolation" with my specific setup.

Fixture data. Some users have fixture data in JSON, YAML, databases, or API servers and want to automatically turn this data into stories.

On databases, or API servers – I’ve also raised this on #23176, I think just worth clarifying whether your RFC here proposes a replacement for this fixture data loading at build time only or both build time and runtime in the browser. As far as I understand it’s just build time.

Indexer API

How is this applicable to StoriesOf users? We’ve put together a proof of concept using the Indexer API that programmatically generates stories:

Could you share your implementation of defineStories or pseudo-code so it’s clearer how this is meant to integrate with the Indexer API?

I think this solves the main use case I had for storiesOf. I have two questions but I think I know the answer in both cases, just want extra clarity:

• Is it possible to create stories across multiple categories / folders / components with this API?
• Would I have to create multiple files if I want to generate stories with different baseCsf?

[shilman]

Could you share your implementation of defineStories or pseudo-code so it’s clearer how this is meant to integrate with the Indexer API?

I've updated the Stackblitz demo with some implementation notes. Hopefully that is sufficient!

Is it possible to create stories across multiple categories / folders / components with this API?

Yes, each file is effectively it's own component, just like CSF (it's getting transpiled to CSF under the hood).

Would I have to create multiple files if I want to generate stories with different baseCsf?

Exactly. People like storiesOf because it's possible to generate a bunch of stories for a bunch of different components in a single file, but unfortunately that's not the case here.

[meck93]

your RFC here proposes a replacement for this fixture data loading at build time only or both build time and runtime in the browser. As far as I understand it’s just build time.

@shilman I'd be curious to know if there is the idea to support loading stories at runtime in the browser (e.g., to support indexing and showing stories that are fetched from another remote Storybook deployment at runtime in the browser).

[shrey27]

Hi @shilman

I understand the issues and limitations that arise due to the current usage of storiesOf API. But my need is very specific. For my current projects, I want to add CSF, test runners, and assertion-based unit testing (with interactions addon).

As all these features are available in later versions of Storybook, that run on Node 16, I cannot switch from Node 14 to 16 as of now due to some project concerns.

Is there any way to utilize these new features in the Node 14 environment if not by using StoryOf ?

[shilman]

Node compatibility is a function of the version of Storybook you're using. The most recent version of Storybook that supports Node 14 is 6.5. You can use CSF, test runner, and play functions in 6.5, all without using StoriesOf. If eventually you're able to upgrade to Node 16+ I'd recommend also upgrading to Storybook 7+, since we made a ton of improvements over 6.5. Hope that helps!

[shrey27]

Thanks for the help. I'm now able to utilize the testing features of Storybook 6.5 with Node 14.

[apastuhov]

Hi, thanks for the great work on Storybook! I would like to share my thoughts about this RFC.

export default { title: 'Button' };
export const Combos = () => {
  const propsCombos = generate(); // same as above
  <Grid>{propsCombos.map(props => <Button {...props} />)}</Grid>
};

It is a good workaround, but as result it is a single story, and not a separated / isolated stories. So it may lead to issues with snapshot tests, and 1 broken variant will break them all. Stories are great because each of them is isolated and does not affect another one.

Storybook Variants Addon is good solution for typical use-case when it is just a 1 component with several arguments and you need to view all combinations at glance. I would recommend to build this into an official Storybook feature at some point in the future. Because it will satisfy most users who uses storiesOf to achieve this goal.

Indexer API is great but it may be hard to debug/maintain and guarantee stability of stories generated during runtime.

Taking into consideration the importance of static analysis and desire of developers to automate everything, I would suggest to review code-gen approach:

1. Introduce new type of file, like MyComponent.stories-gen.tsx, this file may look like this:

import { StoryBuilder } from '@storybook/codegen';
import type { Meta, StoryObj } from '@storybook/react';
import MyComponent from './MyComponent';

const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  parameters: { layout: 'centered' },
};

type Story = StoryObj<typeof meta>;

fetch('https://my-api.com/emails')
  .then(res => res.json())
  .then(emailSettings => {
    // generic here is just as example
    const builder = new StoryBuilder<Meta<typeof MyComponent>>(meta);
    for (const email of emailSettings) {
      // generic here is just as example
      builder.addStory<Story>({
        name: email.type,
        args: {
          email,
        },
      }); 
    }
    builder.generate();
  });

Another example, when I am just lazy to write all stories manually and I know that I have enum with all possible values, so I can generate stories based on it. It is similar to Variants, but in this case each "variant" is a separate story.

import { StoryBuilder } from '@storybook/codegen';
import type { Meta, StoryObj } from '@storybook/react';
import { MyEnum } from 'enums';
import MyComponent from './MyComponent';

const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  parameters: { layout: 'centered' },
};

type Story = StoryObj<typeof meta>;

const builder = new StoryBuilder(meta);

for (const i in MyEnum) {
  builder.addStory<Story>({
    name: MyEnum[i],
    args: {
      value: MyEnum[i],
    },
  }); 
}

builder.generate();

So user has all benefits of meta / CSF / types, but also can have dynamic stories. It is a good balance between flexibility and compatibility with all other Storybook Addons and features.

2. Run storybook codegen which will execute all *.stories-gen.* files one by one, validate / build & generate ./__generated__/MyComponent.stories.tsx file with all stories based on meta / CSF. It should be a separate tool, no need to integrate it into storybook dev -p 6006 command and change existing process just to provide flexibility.

In case of any problems with generated stories - developer will have an ability to play around it, because it is just a generated file, and he can always fix it manually, debug, etc..

Important part that generated stories may be committed to the repository, so it will be available for all developers and any changes caused by fixtures/api may be checked during code review process.

@shilman what do you think about such code-gen approach?

[shilman]

@apastuhov Sorry for the slow response -- just seeing this now. I think your story-gen approach is a fantastic way to deal with dynamically generate stories. I don't think we will support this directly in Storybook itself, but it's perfectly fine to layer other tooling on top of the static CSF and storybook will support those generated stories just fine.

[Mexflubber]

@apastuhov I really like your proposal. I was looking exactly for something like that. How are you doing that nowadays ? I feel a bit lazy and don't want to maintain writing 128 cases for a story.

[lzl124631x]

Hi @apastuhov I can't find @storybook/codegen. Is that internal?

We are using Percy to generate screenshots for all the stories. I haven't used Storybook Variants Addon, but I think it won't work for our case because currently we need to have separate stories for the different variable combinations. Currently I have to do something like this. I really need the capability of adding dynamic stories.

[samesfahani-tuplehealth]

The Stackblitz seems broken at the moment -- Any chance it can be updated?

[shilman]

Sorry about that! Looks like when I updated the code to use 7.4, I saved the changes to a fork and not to the original. I went back and updated the original and it should work now.

[samesfahani-tuplehealth]

There is still one compilation error in preset.ts, but overall works.

Would love to see this baked into SB in the future; we rely on dynamic stories (currently being done through code generation) to test a wide array of different scenarios. It's a bit messy checking in gen code, but it works. I am going to avoid the approach in the POC only because I want to keep our config, plugin files, and deps simple. Will migrate our approach to whatever is baked into SB in the future.