[RFC] Improve preset API

[tobiasdiez]

Summary

Suggestions on how to improve the API for presets.

Problem Statement

The current implementation relies on a couple of "magic" constructions such as

• The presence of a preset.js file at the root (which needs to be in cjs - what if we want to have a module in esm?)
• The presence of certain exports such as viteFinal and webpackFinal - without any natural type support and typos are also only discovered relatively late in the dev cycle.

Non-goals

No response

Implementation

Add a defineStorybookPreset method that bundles and declares all allowed objects/features of a preset.

Proposed API for presets:

import { defineStorybookPreset, createResolver, addProjectAnnotations } from '@storybook/kit'

export default defineStorybookPreset({
  setup() {
    const resolver = createResolver(import.meta.url)

    addProjectAnnotation({
      src: resolver.resolve('runtime/customDecorator.js'),
    })
  },
  viteFinal(config, options) {
  config.plugins.push(
    new MyCustomPlugin({
      someOption: true,
    }),
  );
 
  return config;
}
})

And to load the preset, just try to import the preset using node/jiti, instead of relying on the special preset.js file.

Prior Art

This is essentially a copy of Nuxt's plugin system which works very well in my experience.

Deliverables

No response

Risks

No response

Unresolved Questions

• Using a to do list makes it easy to resolve the questions as we move the RFC along.

Alternatives considered / Abandoned Ideas

No response

[JReinhold]

I completely agree with your problem statement, and also with the idea of defineStorybookPreset to improve the typing experience.

But I think we should instead draw inspiration from Vite's plugin system and ESLint's recent flat config changes, where the user in their config imports plugins/addons/presets/etc., instead of using a magic name string that Storybook then internally tries to load the best it can. We have lots of issues today with trying to load these string-based presets non-trivial setups like monorepos where the package might not be located where we'd expect, or PnP-based package managers that have their own module loading mechanism we need to hook into.

To give an idea of what I mean, instead of this current config:

// .storybook/main.js
export default {
  addons: ['@storybook/addon-a11y'],
  framework: '@storybook-vue/nuxt'
};

I'd propose this:

// .storybook/main.js
import a11yAddon from '@storybook/addon-a11y';
import nuxtStorybook from '@storybook-vue/nuxt';

export default {
  addons: [a11yAddon()],
  framework: nuxtStorybook()
};

This doesn't exactly counter your idea, only the part about loading preset.js files, etc. because in this paradigm, we wouldn't care at all about how the preset files are located/defined in a package, as it would be up to the user to import it, so it could be called whatever the package author wanted.

---

@ndelangen and I briefly experimented with this direction over a year ago and IIRC he was able to make this work even in a backwards compatible way.
It would be a big shift (especially when considering existing docs/literature/tutorials/videos out there), but I think it would be the right long-term call.

[tobiasdiez]

I like this idea. It's, however, somewhat orthogonal to this RFC. You can have the defineStorybookPreset helper with string-based addons names or with importing addons manually.

Btw, I'm skeptical that using `import plugin from 'xyz`` will solve the loading issues you mentioned. Your second example is equivalent to

export default {
  addons: [await import('@storybook/addon-a11y')],
  framework: await import('@storybook-vue/nuxt')
};

which is essentially what storybook is currently doing and involves the same "magical strings" (i.e. the module name). So you will encounter the same issues, if @storybook-vue/nuxt is not declared a dependency of the parent of the .storybook folder. There are two main differences:

• Here the import statement has the context that it is invoked from the .storybook/main file so node/bun/whatever can resolve the import based on this knowledge. This becomes handy when you want to specify addons/frameworks etc from within another addon/framework that is declared a dependency. We had issues like this in the nuxt module. But the workaround is simple: just resolve the name of the dependency in the addon based on the current module and then pass the absolute path to storybook, see https://github.com/nuxt-modules/storybook/blob/c19c93cf7413be0fc3fc2101d19fc54b6787341e/packages/storybook-addon/src/preset.ts#L282-L284. To make this even easier, storybook could expose the createResolver method (as in the example above).
• You can pass options to the framework/addon in a convenient way. For me, this is the biggest advantage of the module-based plugin system.

[shilman]

Agree it's orthogonal, and like @JReinhold am in favor of a definePreset type helper as you've proposed.

The context here is that our users hate format changes (even non-breaking ones!), so every format change should be designed holistically, in relation to other changes that we are considering. In this case, your RFC relates to two other changes that we're considering:

1. @JReinhold 's change above, which is not currently planned
2. @kasperpeulen 's factory proposal, which is a more elaborate version of @AriPerkkio 's defineMeta

For me the biggest preset-related change that we have on deck -- and actually plan to start developing in early Jan -- is moving preview annotations out of presets and into the preview file directly, as described in the factory proposal. This change is a step backwards from a preset perspective; addons would need to be registered twice (once in the preset and once in the preview). However, it gives us types for parameters and also removes one layer of magic from Storybook, since the "inheritance chain" from addons to preset to meta to stories becomes explicit in code.

@tobiasdiez I'm curious (1) whether you have thoughts on @kasperpeulen 's proposal, and (2) how it would affect this proposal (if at all) if preview annotations were no longer part of the equation.

[tobiasdiez]

I like the general idea of the factory proposal, and think it's very much in the same spirit as the proposed definePreset helper. Will have a closer look at the other proposal later.

I don't think the preview annotations would result in any changes to definePreset, except of course that the field preview would be removed.