Docs: Support Rolldown bundler module namespace objects #33280

akornmeier · 2025-12-04T13:51:40Z

What I did

When using vite-rolldown, bundled code creates different object references for the same module imported from multiple files. This caused Map.get() lookups to fail since Maps use object identity.

Add fallback lookup by .default property in resolveModuleExport()
Handles bundlers that don't preserve ES module namespace identity
Add tests for Rolldown compatibility scenarios

Closes #31879

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

stories
unit tests
integration tests
end-to-end tests

Manual testing

Cloned the repro repo posted in the GitHub issue: https://github.com/beaussan/repro-storybook-rolldown-story-of

Installed Storybook from my local tarball created after the update
Reinstalled dependencies, built project, ran Storybook, confirmed fix validity (tarball attached to this comment)

Documentation

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

Checklist for Maintainers

storybook-10.2.0-alpha.3.tgz

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

Bug Fixes
- Enhanced compatibility with bundlers that don't preserve module namespace identity (e.g., Rolldown) by improving module export resolution, ensuring correct default export handling.
Tests
- Added comprehensive tests to verify proper reference and module resolution in bundler compatibility scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

When using vite-rolldown, bundled code creates different object references for the same module imported from multiple files. This caused Map.get() lookups to fail since Maps use object identity. - Add fallback lookup by .default property in resolveModuleExport() - Handles bundlers that don't preserve ES module namespace identity - Add tests for Rolldown compatibility scenarios Fixes storybookjs#31879

Copilot

Pull request overview

This PR fixes an issue where the Rolldown bundler creates different object references for the same module imported from multiple files, causing Map.get() lookups to fail. The solution adds a fallback lookup mechanism that checks the .default property when direct lookup fails, maintaining compatibility with bundlers that don't preserve ES module namespace object identity.

Key changes:

Add fallback lookup in resolveModuleExport() method to check .default property when direct Map lookup fails
Add comprehensive unit tests for Rolldown compatibility scenarios

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
code/core/src/preview-api/modules/preview-web/docs-context/DocsContext.ts	Implements fallback lookup logic in `resolveModuleExport()` to handle bundlers like Rolldown that create different namespace object references
code/core/src/preview-api/modules/preview-web/docs-context/DocsContext.test.ts	Adds unit tests for Rolldown compatibility in both `referenceMeta` and `resolveOf` test suites, plus a test for error handling with non-module objects

code/core/src/preview-api/modules/preview-web/docs-context/DocsContext.test.ts

- Align expected error message in referenceMeta test with the more helpful message in DocsContext that suggests the user may have mistakenly referenced their component instead of their CSF file

coderabbitai · 2025-12-05T07:53:53Z

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

📝 Walkthrough

Walkthrough

Adds a fallback resolution mechanism in DocsContext to handle bundlers like Rolldown that don't preserve module namespace identity. When direct lookup fails and the object contains a .default property, the code now attempts resolution using that default export. Corresponding tests verify this compatibility path.

Changes

Cohort / File(s)	Change Summary
Module resolution fallback `code/core/src/preview-api/modules/preview-web/docs-context/DocsContext.ts`	Introduces fallback lookup mechanism: when direct module export lookup fails, checks if the input object has a `.default` property and attempts resolution using that instead. Handles bundlers with inconsistent module namespace identity.
Rolldown compatibility tests `code/core/src/preview-api/modules/preview-web/docs-context/DocsContext.test.ts`	Adds tests for referenceMeta and resolveOf to verify handling of Rolldown-style module objects with shared `.default` exports, and validates error handling for non-module objects passed to referenceMeta.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Fallback logic verification: Confirm the fallback mechanism triggers only when appropriate and doesn't mask legitimate resolution failures
Test coverage: Verify tests cover both success and failure paths for Rolldown-style modules and non-module object rejection
Edge cases: Check handling of objects that have a .default property but should not use the fallback path

✨ Finishing touches

📝 Generate docstrings

📜 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 7bd55eb and baf7766.

📒 Files selected for processing (2)

code/core/src/preview-api/modules/preview-web/docs-context/DocsContext.test.ts (2 hunks)
code/core/src/preview-api/modules/preview-web/docs-context/DocsContext.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (8)

**/*.{test,spec}.{ts,tsx}

📄 CodeRabbit inference engine (.cursorrules)

**/*.{test,spec}.{ts,tsx}: Test files should follow the naming pattern *.test.ts, *.test.tsx, *.spec.ts, or *.spec.tsx
Follow the spy mocking rules defined in .cursor/rules/spy-mocking.mdc for consistent mocking patterns with Vitest

Files:

code/core/src/preview-api/modules/preview-web/docs-context/DocsContext.test.ts

**/*.test.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (.cursor/rules/spy-mocking.mdc)

**/*.test.{ts,tsx,js,jsx}: Use vi.mock() with the spy: true option for all package and file mocks in Vitest tests
Place all mocks at the top of the test file before any test cases
Use vi.mocked() to type and access the mocked functions in Vitest tests
Implement mock behaviors in beforeEach blocks in Vitest tests
Mock all required dependencies that the test subject uses
Each mock implementation should return a Promise for async functions in Vitest
Mock implementations should match the expected return type of the original function
Mock all required properties and methods that the test subject uses in Vitest tests
Avoid direct function mocking without vi.mocked() in Vitest tests
Avoid mock implementations outside of beforeEach blocks in Vitest tests
Avoid mocking without the spy: true option in Vitest tests
Avoid inline mock implementations within test cases in Vitest tests
Avoid mocking only a subset of required dependencies in Vitest tests
Mock at the highest level of abstraction needed in Vitest tests
Keep mock implementations simple and focused in Vitest tests
Use type-safe mocking with vi.mocked() in Vitest tests
Document complex mock behaviors in Vitest tests
Group related mocks together in Vitest tests

Files:

code/core/src/preview-api/modules/preview-web/docs-context/DocsContext.test.ts

**/*.{js,jsx,json,html,ts,tsx,mjs}