contribution/framework

25 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Storybook framework definition

A Storybook framework is a node package that enables out-of-the-box support for either a metaframework (Next.js, NuxtJS, SvelteKit) or a combination of builder (Webpack, Vite) plus renderer (React, Angular, Vue 3, web components, etc). For metaframeworks, the Storybook framework also takes care of additional configuration necessary to make Storybook behave similarly to apps generated by the metaframework.

Framework package naming convention

The framework package name should start with 'storybook-framework-' and then correspond to what the framework supports. For metaframeworks, use 'storybook-framework-<metaframework-name>' (e.g., 'storybook-framework-svelte-kit'). When targeting a combination of renderer and builder without a metaframework, use 'storybook-framework-<renderer>-<builder>' (e.g., 'storybook-framework-stencil-vite').

Framework package.json required exports

A Storybook framework package.json must include exports for: the root (.), ./preset, and ./package.json. If the framework has a preview.js file, that must also be exported. The exports should define types, require, and import paths for each.

Framework package.json template structure

A framework package.json should include: name starting with 'storybook-framework-', version, description, keywords, homepage, bugs.url, repository (type: 'git', url, directory), license: 'MIT', exports object with root, preset, and optionally preview.js paths, main, module, types, files array, scripts (check and test), dependencies on storybook and relevant builder/renderer packages, devDependencies on metaframework/builder versions being targeted, peerDependencies specifying supported versions, engines.node >= 20.0.0, and publishConfig.access: 'public'.

Framework preset.js responsibility

The preset.js file configures the Storybook core (specifying which builder and renderer are used by the framework), the builder (via webpackFinal or viteFinal export), babel configuration (via the babel export), any necessary addons, and any available options for the framework.

Framework preview.js optional configuration

The preview.js file is optional and configures the rendering of stories, such as global decorators or initializing runtime config needed for the framework to behave as expected. If a framework requires this file, it must also configure the previewAnnotations in preset.js.

Framework types.ts export

If authoring a framework in TypeScript (recommended), export the StorybookConfig type which reflects the available options of the framework.

Framework testing and version support strategy

When creating a framework, determine which versions of each library it will support. Account for changes within different versions or split the framework into different versions/packages to support each library version. Add integration tests for the various library versions the framework supports to speed up maintenance.

Framework documentation as first step

Before writing code, write a helpful README that contains installation instructions and a list of available features. Use the README for @storybook/nextjs as a template. Writing documentation first helps guide other work on the framework.

Framework goal and design principle

The goal of a Storybook framework is to make Storybook behave out-of-the-box as similarly as possible to the metaframework or builder-renderer combination being targeted. For metaframeworks, attempt to recreate any builder or babel configuration provided by the metaframework, respecting the user's existing project configuration as much as possible.

Framework Node.js version requirement

Storybook frameworks must support Node.js version 20.0.0 or higher, as specified in the package.json engines field.

Create reproduction with npx storybook sandbox

To create a reproducible test case for a Storybook issue, run the command `npx storybook@next sandbox` in a terminal. You can append a template name to filter results, for example `npx storybook@next sandbox react`. After running the command, choose a template and enter a location for the reproduction. If no full path is provided, the reproduction will be generated in the current directory.

Prerequisites for creating a reproduction

To create a Storybook reproduction, ensure you have: Yarn installed on your local development machine, a GitHub account for hosting the reproduction code, and a Chromatic account for publishing the Storybook.

Install and configure third-party dependencies and addons in reproduction

Before adding code to a reproduction, install and configure any necessary third-party packages related to the issue, such as CSS frameworks like Tailwind. Also install and configure any Storybook addons that relate to the issue, such as @storybook/addon-a11y.

Include minimum stories to replicate the issue

When creating a Storybook reproduction, include the minimum amount of stories that will replicate the issue to help fix it faster.

Host reproduction on GitHub and publish with Chromatic

After creating a reproduction locally, host it by creating a new repository on GitHub. Then publish it using Chromatic, a free publishing service created by the Storybook maintainers that allows you to deploy and host your reproduction safely and securely in the cloud.

Submit reproduction to Storybook issue tracker

When submitting an issue to the Storybook issue tracker at https://github.com/storybookjs/storybook/issues/new/choose, provide a detailed description of the problem and add both the GitHub repository link and the deployed reproduction URL to help with the triage process.

Storybook versioning follows Semantic Versioning

Storybook packages follow Semantic Versioning (semver) with a structured release process to ensure stability, compatibility, and smooth upgrade paths for users.

Storybook release channels

Storybook publishes on two channels: the stable channel with tag 'latest' (installed via npm create storybook@latest) for latest stable releases, and the pre-release channel with tag 'next' (installed via npm create storybook@next) for the latest pre-release versions.

Storybook version support policy

The latest major version receives all security fixes. The previous two majors receive security patches only for High or Critical CVSS vulnerabilities. Older versions receive no patches. Within the current major, only the latest minor version receives patches. Most fixes and new work go into the next minor (or sometimes major) and are not backported.

Storybook major release cadence

Major releases occur roughly once per year on the stable (latest) channel. They introduce breaking changes and significant new features to keep up with ecosystem changes, evolve architecture and APIs, and improve speed and usability. Major releases go through alpha, beta, and rc (release candidate) pre-releases before reaching stable. They include automated migrations and comprehensive migration guides when manual changes are necessary.

Storybook minor release cadence

Minor releases occur roughly every 8 weeks on the stable (latest) channel. They deliver new features, enhancements, and non-breaking improvements. Each minor release may be preceded by an alpha pre-release (e.g. x.y.0-alpha).

Storybook patch release cadence

Patch releases are issued as needed, but only for the current minor version. They include critical bug fixes and security updates on the stable (latest) channel. Patch releases are not pre-released.

Storybook pre-release cadence

Pre-releases are created regularly on the pre-release (next) channel to gather early feedback and ensure stability before official release. Minor version stable releases are preceded by pre-releases with an alpha tag (e.g. x.y.0-alpha), with no patch pre-releases. Major version stable releases are preceded by a fuller cycle of alpha, beta, and rc pre-releases.

Storybook migration complexity from v6 to v7+

Storybook versions prior to 7 had a different architecture, making upgrades from v6 to newer versions more challenging. Starting in v7, the focus shifted to smoother migrations, and upgrades from v7 to v8, and v8 to v9 and beyond, should feel significantly easier thanks to automigrations and better tooling.

Give your agent this brain