Core: Add support for beforeAll hook

[ghengeveld]

Closes #28268
Depends on ComponentDriven/csf#96 ✅

What I did

This adds the concept of a beforeAll function, which runs when the Storybook preview is initialized or preview annotations are updated. In general, beforeAll runs once, before any loaders, decorators or stories. The API is similar to Vitest's beforeAll (except that timeout is not supported):

type Awaitable<T> = T | Promise<T>;
type CleanupFn = () => Awaitable<void>;
type BeforeAll = () => Awaitable<void | CleanupFn>;

beforeAll may be synchronous or asynchronous, and may return a cleanup function which may also be synchronous or asynchronous.

beforeAll may be specified as an export in preview.js (by addons or in user's Storybook config) or in a file referenced by previewAnnotations in main.js.

// .storybook/preview.js

export const beforeAll = () => {
  // ... do something

  return () => {
    // ... cleanup
  }
}

When multiple beforeAll hooks are specified, they will be executed sequentially (and awaited) in the following order:

1. Addon hooks (in order of addons array in .storybook/main.js)
2. Annotation hooks (in order of previewAnnotations array in .storybook/main.js)
3. Preview hook (via .storybook/preview.js)

The cleanup function acts like an "afterAll", but is not guaranteed to run because this code typically runs in the browser. However, the Storybook test runner may invoke this function to clean up between test runs. Also, when modifying preview.js or a previewAnnotations file, cleanup will run before reinitializing beforeAll. Cleanup functions are executed sequentially, in reverse order of initialization:

1. Preview cleanup
2. Annotation cleanup (in reverse order)
3. Addon cleanup (in reverse order)

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

1. Create a sandbox
2. Create .storybook/before-all.js with the example beforeAll hook below.
3. Update .storybook/preview.js to add beforeAll (see below)
4. Update .storybook/main.js to add previewAnnotations (see below)
5. Run the sandbox and check your browser console
6. Verify you see both hooks run (before-all.js goes first)
7. Modify and save preview.js, then check your browser console again
8. Verify you see the cleanup happen in reverse order before the updated hooks run in their usual order.

Example beforeAll hook:

// .storybook/preview.js or .storybook/before-all.js
export const beforeAll = () => {
  console.log('### beforeAll in preview/annotation');
  return () => {
    console.log('### afterAll in preview/annotation');
  };
};

Update the log lines so you can distinguish between files (preview.js, before-all.js).

// .storybook/main.js
const config = {
  // ... other stuff

  previewAnnotations: ['.storybook/before-all.js']
};
export default config;

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This pull request has been released as version 0.0.0-pr-28255-sha-9d564a0d. Try it out in a new sandbox by running npx [email protected] sandbox or in an existing project with npx [email protected] upgrade.

More information

Published version	0.0.0-pr-28255-sha-9d564a0d
Triggered by	@ghengeveld
Repository	storybookjs/storybook
Branch	beforeAll-hook
Commit	9d564a0d
Datetime	Mon Jun 24 13:56:48 UTC 2024 (1719237408)
Workflow run	9646676768

To request a new release of this pull request, mention the @storybookjs/core team.

core team members can create a new canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=28255

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 6f660f0. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 1 target

• nx run-many -t build -c production --parallel=3

---

Sent with 💌 from NxCloud.

[kasperpeulen]

Looks good!

[storybook-bot]

Failed to publish canary version of this pull request, triggered by @ghengeveld. See the failed workflow run at: https://github.com/storybookjs/storybook/actions/runs/9644536695

[ghengeveld]

e2e-dev is failing but not because of the work in this PR...