[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.