[RFC] Specify feature flags in preview.js

[shilman]

Summary

Storybook uses feature flags to configure transitional behaviors, e.g. to expose an experimental or breaking change in a minor release. This RFC proposes to move those flags from main.js to preview.js to make them available in Storybook's new Portable Stories.

Problem Statement

Feature flags

Feature flags are used for transitional behaviors, either to opt-in to future behavior or legacy behavior.

For example, when we rearchitected the guts of Storybook in 7.0. 6.x users could opt-in to the new behavior using:

// .storybook/main.js
export default {
  stories: [...],
  features: { storyStoreV7: true },
}

Later, in Storybook 7.0, that new behavior was the default, but we allowed them to opt-out using features: { storyStoreV7: false }

Portable stories

We recently introduced the concept of "portable stories" to allow users to reuse their stories and the Storybook runtime outside of Storybook, for example in Playwright, Jest, and so on. We are also making a bigger bet on portable stories as the backbone of our new Vitest-based test runner.

The problem

The problem is that the contents of main.js, is not available in portable stories, since the Storybook code that reads the flags out of main.js and injects globals.FEATURES into Storybook's "manager" and "preview" does not run in portable stories. Therefore, feature flags will work in Storybook but won't be available outside of Storybook.

An actual example of this is a transitional feature for Svelte 5 to support the children arg as the default slot. Full discussion on the PR.

Non-goals

We are not interested in expanding the scope of portable stories to accommodate main.js settings because that significantly expands its surface area.

Implementation

We are proposing a new top-level preview annotation to replace the main.js features flag.

So instead of:

// .storybook/preview.js
export default {
  features: { someFeature: true }
}

You would write:

// .storybook/preview.js
export default {
  features: { someFeature: true }
}

Then, Storybook would statically analyze preview.js in node and make these feature flags available in both Node and manager in globals.FEATURES.

And features.someFeature would be available on the story context in the preview, and addons/core features that want to be portable-stories compatible should reference that instead of globals.FEATURES.

Prior Art

No response

Deliverables

1. Add features types to @storybook/csf
2. Implement preview.js features handling to
   a. Add it to the story context
   b. Add it to globals.FEATURES
   c. Error if it is used in conjunction with main.js features
3. Deprecate main.js features in 8.x and remove in 9.0
4. Update documentation including MIGRATION.md

Risks

No response

Unresolved Questions

• Are there preview use cases where the story context is not available? If so, where can we store this info to make it portable stories compatible?
• Are there use cases where we want to use feature flags that are not statically analyzeable like process.env.ENABLE_SOME_FEATURE?

Alternatives considered / Abandoned Ideas

There are a couple counter-proposals already:

1. Just use parameters instead. That way we don't need to add a new construct AND we get something that is configurable on a per-story basis.
2. Use parameters.features for stuff that is globally configurable only.

I think in some cases parameters is the right solution. For example, when we made features.experimentalRSC for React Server Components compatible with portable stories, we used an existing parameters.react.rsc parameter and basically ignored the experimentalRSC feature. In this case it's a requirement that RSC be configurable on a per-story basis, and we already had parameter support.

In the case of Svelte behavior there is also an argument for making it configurable on a per-story basis e.g. parameters.svelte.childrenAsDefaultSlot. However, I think the main thing is that we want Svelte 4 to behave one way and Svelte 5 to behave another. And therefore I think the features mechanism is more appropriate.

Furthermore, even if the Svelte case made sense as a parameter, it is useful to have a uniform mechanism for feature flags that is both supported by Storybook AND portable stories, and the proposal above is that.

[JReinhold]

I'm fine with the idea overall.

Then, Storybook would statically analyze preview.js in node and make these feature flags available in both Node and manager in globals.FEATURES.

What constraints does this impose? Feature flags can only be top-level, static booleans, not referencing other variables? Ie. similar to tags, but booleans instead of strings?

[shilman]

Yeah. The other difference from tags is that they compose hierarchically, whereas features only make sense at the project level.