Docs: Hotfix addon migration guide to match addon-kit

[Sidnioulz]

What I did

Made changes to the addon migration guide to match recent changes made by @ndelangen on the addon-kit.

Checklist for Contributors

Testing

N/A

Documentation

• Add or update documentation reflecting your changes

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 publish.yml --field pr=<PR_NUMBER>

Summary by CodeRabbit

Release Notes

• Refactor
  • Modernized addon system to use ES modules for improved module resolution and loading efficiency
  • Added new manager-helpers export point for addon developers
  • Enhanced type definitions for preview functionality

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request migrates an addon from CommonJS to ES Modules. Changes include updating TypeScript configuration to target ESM, converting package.json export mappings to ESM-style defaults, replacing CommonJS preset.js with ESM exports, updating local addon loading to use import.meta.resolve, and adjusting build configuration for ESM-first strategy.

Changes

Cohort / File(s)	Summary
TypeScript & Build Configuration tsconfig.json, tsup.config.ts	Updated TypeScript module target from "preserve" to "esnext"; changed target from "es2023" to "esnext"; updated lib to ["esnext","dom","dom.iterable"]; changed rootDir from "./src" to "."; included tsup.config.ts in includes; adjusted build configuration to favor managerEntries/previewEntries and ESM externalization strategy.
Package Exports & Metadata package.json	Removed CommonJS mappings; added ESM-style defaults to "." export ("default": "./dist/index.js"); updated "./preview" export with "types" and "default" fields; changed "./preset" from "./dist/preset.cjs" to "./dist/preset.js"; added new "./manager-helpers" export ("./dist/manager-helpers.js"); added "src/manager-helpers.ts" to bundler managerEntries.
Preset Export preset.js	Converted from CommonJS (module.exports = require('./dist/preset.cjs')) to ES module export (export \* from './dist/preset.js').
Local Addon Loading local-preset.cjs (removed), local-preset.ts (added), main.ts	Replaced CommonJS local-preset.cjs with ESM-based local-preset.ts using import.meta.resolve for addon preset resolution; updated main.ts to utilize import.meta.resolve for addon preset loading.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• package.json export mappings: Verify all export paths correctly resolve to intended distribution files and that no breaking changes occur for existing consumers.
• import.meta.resolve usage: Confirm compatibility with target Node.js version and runtime environment; validate that addon preset resolution works as expected.
• Build output verification: Ensure tsup correctly generates ESM outputs for all entry points (manager, preview, preset, manager-helpers).
• Backward compatibility: Check if this migration introduces breaking changes for consumers of the addon's public API surface.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch hotfix-addon-migration-guide

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between aba3791 and 9b3a093.

📒 Files selected for processing (1)

• docs/addons/addon-migration-guide.mdx (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

docs/**

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Update documentation under docs/ for significant changes, including migration guides for breaking changes

Files:

• docs/addons/addon-migration-guide.mdx

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Danger JS
• GitHub Check: get-parameters
• GitHub Check: Core Unit Tests, windows-latest

🔇 Additional comments (6)

docs/addons/addon-migration-guide.mdx (6)

223-241: ESM tsconfig.json changes are accurate and well-explained.

The TypeScript configuration diff correctly shows the migration to ESM-first approach. The changes to target, lib, rootDir, and include align with ESM build requirements. The addition of tsup.config.ts to includes ensures proper type checking of the build configuration.

---

253-279: Local addon loading ESM pattern is clear and follows modern import semantics.

The new local-preset.ts example correctly uses import.meta.resolve() with fileURLToPath() for dynamic resolution of relative paths in ESM, and the main.ts update properly references the TypeScript preset file. This pattern is well-suited for development Storybook instances.

---

245-251: preset.js ESM migration is concise and correct.

The change from CommonJS module.exports to ES module export syntax is appropriate. The comment removal ("this file is slightly misleading...") reduces confusion about why the file must be named preset.js rather than preset.cjs.

---

299-328: Optional exportEntries removal is well-documented with practical examples.

The explanation clearly states why exportEntries was removed and provides actionable guidance for the migration to previewEntries and managerEntries. The manager-helpers example is particularly helpful for addon authors exporting manager-specific utilities like renderLabel.

---

1-361: Documentation comprehensively covers Storybook 10.0 ESM-only addon migration.

The guide follows a logical structure: dependency updates → key changes (with detailed diffs) → local development setup → optional improvements. All code examples use correct ESM syntax, file paths are properly explained, and cross-references to addon-kit and broader migration resources are included. The distinction between required and optional changes is clear.

Per coding guidelines, this migration guide appropriately documents breaking changes for addon developers updating to Storybook 10.0.

---

69-197: Based on the script output and web search, I can verify the key configuration details:

NODE_TARGET version matches: The script confirmed the addon-kit esm-only branch uses const NODE_TARGET = 'node20.19'; which matches the documentation diff.

Format configuration matches: The grep output shows format: ['esm'], which aligns with the documented change to ESM-only format.

Context verified: Storybook 10 is switching to ESM-only, which explains the migration shown in the diff including removal of exportEntries and the simplified build configuration.

The documented changes are accurate and align with the addon-kit implementation for Storybook 10's ESM-only approach. The configuration shows the expected modernization: simplifying bundling to ESM format only, updating Node target to the minimum supported version with a patch number, and externalizing framework packages.

Update the documentation to clarify that exportEntries removal is intentional for Storybook 10 ESM-only compatibility and verify all manager/preview/node entry target values match the reference implementation.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 4fb0dfb

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

---

☁️ Nx Cloud last updated this comment at 2025-10-27 15:44:42 UTC

[jonniebigodes]

@Sidnioulz, thanks for catching and adjusting the documentation. Appreciate it 🙏

I've checked, and everything is good on my end.

@ndelangen, if you don't have any objections, we can merge it and make it available as soon as the documentation is published.