Manager: Resolve preview iframe URL against the document base URI

[yatishgoel]

Closes #34733

What I did

When Storybook is hosted under a sub-path, the preview iframe may fail to load, and the manager may hang on the loading spinner indefinitely.

The manager computed the iframe.html URL by string-manipulating the router pathname (location.pathname) instead of resolving it as the browser does for the manager's own relative assets. This produced a wrong URL in two cases:

• Sub-path without a trailing slash (e.g. /storybook): the sub-path was wrongly prepended, pointing the iframe at a non-existent …/iframe.html → preview never connects, infinite loading.
• Custom <base href> (the documented way to host under a sub-path): it was ignored entirely, so the iframe pointed at the wrong location.

The fix resolves iframe.html against the manager document's base URI (document.baseURI) using the URL constructor - the same base the browser uses for the manager's own assets. This honors a custom <base href>, follows the browser's directory rules for paths with/without a trailing slash, and keeps the iframe on the manager's origin. The origin/network options for getStoryHrefs (used for shareable "open in isolation" links) are unchanged.

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

Caution

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

Reproduces the on-prem sub-path hosting from the issue:

1. Build a Storybook: yarn task --task build --start-from auto --template react-webpack5/default-ts (or any template).
2. Serve the static output from a sub-path without a trailing slash — e.g. with a tiny static server / reverse proxy so the app is reachable at http://localhost:8080/storybook (no trailing slash). A quick way: serve a parent folder and place the build under ./storybook, then open http://localhost:8080/storybook.
3. Before the fix: the manager shell loads but stories never do — the preview iframe stays on the loading spinner (the iframe src resolves to a non-existent …/storybook/iframe.html).
4. After the fix: stories load normally; the preview iframe resolves to /iframe.html.
5. Sub-path with a <base href> : in .storybook/main.ts set the builder base to /design-system/ and add managerHead: (head) => \${head}`, build, and serve under /design-system/. The iframe should resolve to /design-system/iframe.html` and stories should load.

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

• Declare whether manual QA will be needed for this PR during the next release, through qa:needed or qa:skip

• 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>

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0e53bd5f-fa55-4067-9482-c93d12b33090

📥 Commits

Reviewing files that changed from the base of the PR and between 8256cee and 10a7f70.

📒 Files selected for processing (11)

• agent-eval/evals/812-first-story-empty-project/package.json
• agent-eval/evals/821-upgrade-from-sb9/package.json
• agent-eval/evals/822-upgrade-from-stable/package.json
• agent-eval/evals/823-setup-outdated-storybook/package.json
• agent-eval/templates/monorepo/package.json
• agent-eval/templates/monorepo/packages/ui/package.json
• agent-eval/templates/reshaped-storybook/package.json
• agent-eval/templates/vite-app/package.json
• code/core/src/manager-api/modules/url.ts
• code/core/src/manager-api/tests/url.test.js
• code/lib/codex-plugin/plugins/storybook/.mcp.json

🚧 Files skipped from review as they are similar to previous changes (11)

• agent-eval/evals/823-setup-outdated-storybook/package.json
• agent-eval/templates/reshaped-storybook/package.json
• agent-eval/evals/822-upgrade-from-stable/package.json
• agent-eval/evals/812-first-story-empty-project/package.json
• agent-eval/templates/monorepo/packages/ui/package.json
• agent-eval/evals/821-upgrade-from-sb9/package.json
• code/lib/codex-plugin/plugins/storybook/.mcp.json
• agent-eval/templates/vite-app/package.json
• code/core/src/manager-api/tests/url.test.js
• agent-eval/templates/monorepo/package.json
• code/core/src/manager-api/modules/url.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

Walkthrough

Adds resolveIframeUrl to resolve iframe.html with the URL API. Updates getStoryHrefs to use manager or document base URLs. Expands URL tests for subpaths and absolute bases. Reorders fixture manifest entries and reformats MCP configuration indentation.

Changes

iframe URL resolution via document.baseURI

Layer / File(s)	Summary
URL resolution helper and getStoryHrefs integration code/core/src/manager-api/modules/url.ts	Resolves iframe.html against the selected base URL and replaces regex-based URL manipulation.
URL resolution test coverage code/core/src/manager-api/tests/url.test.js	Adds document base URI setup and assertions for root, subpath, nested, trailing-slash, and absolute URL cases.

Fixture manifest and MCP formatting

Layer / File(s)	Summary
Fixture and template manifest ordering agent-eval/evals/*/package.json, agent-eval/templates/**/*.json	Reorders package manifest entries without changing commands or configuration values.
MCP configuration formatting code/lib/codex-plugin/plugins/storybook/.mcp.json	Replaces tab indentation with spaces without changing the configuration value.

Merge Risk: ⚪ Minimal · up to 10a7f

The PR updates preview iframe URL resolution for sub-path and custom base-URI hosting; no actionable merge-blocking risk remains beyond normal checks and review.

---

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

[storybook-app-bot]

Package Benchmarks

^{Commit: b341c6b, ran on 12 September 2026 at 09:21:02 UTC}

No significant changes detected, all good. 👏

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.