ESM: Update documentation to use valid ESM #32067

ndelangen · 2025-07-17T12:29:42Z

Works on: #31787

What I did

I updated all documentation to use import.meta.resolve over require.resolve use process.cwd() over __dirname etc.

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

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

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-storybook/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 PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

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

Greptile Summary

This PR updates Storybook's documentation and code snippets to use ESM-compatible syntax instead of CommonJS patterns, as part of Storybook's transition to ESM-only in version 10. The key changes include:

Replacing require.resolve() with import.meta.resolve()
Replacing __dirname with process.cwd()
Removing legacy storiesOf API documentation examples
Converting CommonJS imports to ESM syntax
Renaming the config function to previewAnnotations in preset configurations

These changes are part of a larger initiative (issue #31787) to make Storybook ESM-only, which aims to reduce install size by 37% and address development/debugging pain points caused by having both ESM and CommonJS outputs.

Confidence score: 5/5

This PR is safe to merge as it only updates documentation to reflect current best practices
The changes are consistent across all documentation files and align with the ESM migration goals
Files that need attention: None, as changes are straightforward documentation updates

_{32 files reviewed, 6 comments}
_{Edit PR Review Bot Settings | Greptile}

greptile-apps

Reviewing changes made in this pull request

docs/_snippets/module-aliases-config.md

greptile-apps · 2025-07-17T12:34:24Z

docs/_snippets/vitest-plugin-vitest-config.md

@@ -4,8 +4,7 @@ import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';

-const dirname =
-  typeof __dirname !== 'undefined' ? __dirname : path.dirname(fileURLToPath(import.meta.url));
+const dirname = path.dirname(fileURLToPath(import.meta.url));

 import viteConfig from './vite.config';


style: Move import statements above code to follow ESM best practices

Suggested change

import viteConfig from './vite.config';

import { defineConfig, mergeConfig } from 'vitest/config';

import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';

import path from 'node:path';

import { fileURLToPath } from 'node:url';

import viteConfig from './vite.config';

const dirname = path.dirname(fileURLToPath(import.meta.url));

greptile-apps · 2025-07-17T12:34:25Z

docs/_snippets/vitest-plugin-vitest-config.md

@@ -51,40 +52,41 @@ import { fileURLToPath } from 'node:url';

 import viteConfig from './vite.config';


style: Same import order issue as in React example - move viteConfig import to top

Suggested change

import viteConfig from './vite.config';

import { defineConfig, mergeConfig } from 'vitest/config';

import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';

import path from 'node:path';

import { fileURLToPath } from 'node:url';

import viteConfig from './vite.config';

const dirname = path.dirname(fileURLToPath(import.meta.url));

greptile-apps · 2025-07-17T12:34:25Z

docs/_snippets/vitest-plugin-vitest-config.md

@@ -94,8 +96,7 @@ import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';

-const dirname =
-  typeof __dirname !== 'undefined' ? __dirname : path.dirname(fileURLToPath(import.meta.url));
+const dirname = path.dirname(fileURLToPath(import.meta.url));

 import viteConfig from './vite.config';


style: Same import order issue as in React example - move viteConfig import to top

Suggested change

import viteConfig from './vite.config';

import { defineConfig, mergeConfig } from 'vitest/config';

import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';

import path from 'node:path';

import { fileURLToPath } from 'node:url';

import viteConfig from './vite.config';

const dirname = path.dirname(fileURLToPath(import.meta.url));

docs/_snippets/storybook-addons-preset.md

greptile-apps · 2025-07-17T12:34:28Z

code/addons/docs/docs/frameworks/VUE3.md

 export default {
  addons: [
    {
      name: '@storybook/addon-docs',
      options: {
        vueDocgenOptions: {
          alias: {
-            '@': path.resolve(__dirname, '../'),
+            '@': path.resolve(process.cwd(), 'src'),


syntax: path.resolve() is used without importing path. Add import statement: import { resolve } from 'path'

Suggested change

'@': path.resolve(process.cwd(), 'src'),

import { resolve } from 'node:path';

export default {

addons: [

{

name: '@storybook/addon-docs',

options: {

vueDocgenOptions: {

alias: {

'@': resolve(process.cwd(), 'src'),

},

},

},

},

],

};

nx-cloud · 2025-07-17T12:42:20Z

View your CI Pipeline Execution ↗ for commit ea1fbc3

Command	Status	Duration	Result
`nx run-many -t build --parallel=3`	✅ Succeeded	49s	View ↗

☁️ Nx Cloud last updated this comment at 2025-07-22 14:49:56 UTC

…ove section headings

…ntation

docs/_snippets/module-aliases-config.md

docs/_snippets/storybook-addons-preset.md

docs/api/main-config/main-config.mdx

kylegach

Left a few suggestions to be addressed, but I'll approve to unblock. Thanks!

Co-authored-by: Kyle Gach <[email protected]>

…torybook 10

…okjs/storybook into norbert/esm-docs-changes

remove CJS references from docs about configuring storybook

f03b41a

ndelangen added documentation ci:docs Run the CI jobs for documentation checks only. esm labels Jul 17, 2025

ndelangen requested review from kylegach and jonniebigodes July 17, 2025 12:32

ndelangen self-assigned this Jul 17, 2025

ndelangen marked this pull request as ready for review July 17, 2025 12:33

greptile-apps bot reviewed Jul 17, 2025

View reviewed changes

ndelangen added 3 commits July 17, 2025 14:47

Add note on ESM requirements in main-config documentation

ba4910b

Update main-config documentation to clarify ESM requirements and impr…

ef37c4c

…ove section headings

Add ESM requirements for .storybook/main.* file in migration docume…

13fa584

…ntation

kylegach reviewed Jul 17, 2025

View reviewed changes

docs/_snippets/module-aliases-config.md Outdated Show resolved Hide resolved

kylegach reviewed Jul 17, 2025

View reviewed changes

docs/_snippets/storybook-addons-preset.md Outdated Show resolved Hide resolved

kylegach reviewed Jul 17, 2025

View reviewed changes

docs/api/main-config/main-config.mdx Outdated Show resolved Hide resolved

kylegach approved these changes Jul 17, 2025

View reviewed changes

ndelangen and others added 7 commits July 22, 2025 12:06

Merge branch 'sb10/esm-only' into norbert/esm-docs-changes

92fe4b2

Merge branch 'sb10/esm-only' into norbert/esm-docs-changes

f34e3e2

Update docs/api/main-config/main-config.mdx

f4d1b57

Co-authored-by: Kyle Gach <[email protected]>

Update docs/_snippets/module-aliases-config.md

a73825e

Co-authored-by: Kyle Gach <[email protected]>

Update docs/_snippets/storybook-addons-preset.md

8b38015

Co-authored-by: Kyle Gach <[email protected]>

Add documentation for local addon resolution in migration guide for S…

c35377c

…torybook 10

Merge branch 'norbert/esm-docs-changes' of https://github.com/storybo…

ea1fbc3

…okjs/storybook into norbert/esm-docs-changes

ndelangen merged commit 1c2b4b5 into sb10/esm-only Jul 22, 2025
7 checks passed

ndelangen deleted the norbert/esm-docs-changes branch July 22, 2025 14:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

ESM: Update documentation to use valid ESM #32067

ESM: Update documentation to use valid ESM #32067

Uh oh!

ndelangen commented Jul 17, 2025 •

edited by greptile-apps bot

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

greptile-apps bot Jul 17, 2025

Uh oh!

greptile-apps bot Jul 17, 2025

Uh oh!

greptile-apps bot Jul 17, 2025

Uh oh!

Uh oh!

greptile-apps bot Jul 17, 2025

Uh oh!

nx-cloud bot commented Jul 17, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kylegach left a comment

Uh oh!

Uh oh!

Uh oh!

		@@ -51,40 +52,41 @@ import { fileURLToPath } from 'node:url';

		import viteConfig from './vite.config';

Uh oh!

ESM: Update documentation to use valid ESM #32067

ESM: Update documentation to use valid ESM #32067

Uh oh!

Conversation

ndelangen commented Jul 17, 2025 • edited by greptile-apps bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I did

Checklist for Contributors

Testing

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

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

Greptile Summary

Confidence score: 5/5

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greptile-apps bot Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greptile-apps bot Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

nx-cloud bot commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kylegach left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ndelangen commented Jul 17, 2025 •

edited by greptile-apps bot

Loading

nx-cloud bot commented Jul 17, 2025 •

edited

Loading