feat(start): support serving assets via relative base urls

[EduardF1]

Description

Fixes #5966

When TanStack Start is configured with a relative base path (base: './') to be hosted inside sub-directory setups or iFrames (e.g., Home Assistant add-ons), the asset loader was incorrectly discarding the relative dot and prepending a root slash. Further, Asset.tsx resolved all href URLs absolutely against the browser's origin via new URL(...), destroying the relativity.

This patch:

1. Normalizes relative base paths properly in manifestBuilder.ts without overriding the ./ prefix.
2. Bypasses absolute URL enforcement in Asset.tsx when the path is explicitly relative and running in a document where baseURI isn't strictly absolute.

Testing

Verified output generated by standard build command.

Summary by CodeRabbit

• Bug Fixes
  • Fixed URL handling in embedded deployments to preserve relative paths when needed.
  • Improved asset path resolution for relative path-based configurations.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds support for relative base URL deployments by normalizing asset paths at both build and runtime. Build-time normalization in the manifest builder ensures relative basePaths produce relative asset paths, while runtime normalization in the Script component preserves relative URLs in non-HTTP environments like iFrames.

Changes

Relative Base URL Support

Layer / File(s)	Summary
Asset manifest path normalization for relative basePath packages/start-plugin-core/src/start-manifest-plugin/manifestBuilder.ts	The getAssetPath function normalizes asset URLs when basePath is relative: it adds ./ prefix when basePath is exactly './', and converts leading / to relative form when basePath starts with './', preserving relative paths instead of forcing absolute URLs.
Script element runtime URL normalization packages/react-router/src/Asset.tsx	The Script component's useEffect conditionally preserves explicit ./ relative URLs when the document base is not HTTP (e.g., iframe deployments), while resolving to absolute URLs for HTTP-based bases, with fallback exception handling to the original src.

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

package: start-plugin-core

Poem

🐰 A rabbit hops through iFrame land,
Where ./ paths take a stand,
No more /./ in the light—
Relative URLs work just right! 🌙
Build and runtime, hand in paw,
Keeping addresses just raw.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main feature: adding support for relative base URLs in the Start asset serving system, which directly aligns with the changeset.
Linked Issues check	✅ Passed	The pull request addresses issue #5966 by normalizing relative base paths in manifestBuilder.ts and avoiding absolute URL enforcement in Asset.tsx, enabling proper relative asset URL handling for iFrame deployments.
Out of Scope Changes check	✅ Passed	All changes focus on supporting relative base URLs: URL normalization in manifestBuilder.ts and conditional absolute URL handling in Asset.tsx are directly scoped to the linked issue.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

🧹 Nitpick comments (1)

packages/react-router/src/Asset.tsx (1)

142-144: Preserve ../ relative src only if inputs can generate it

• Search in packages/start-plugin-core/src/start-manifest-plugin/ shows ../ only in internal import paths (not generated manifest href/src), and the packages/react-router/ scan found no src.*../ literals.
• packages/react-router/src/Asset.tsx currently preserves only attrs.src.startsWith('./'); ../... would be normalized via new URL(attrs.src, base).href. Keep the ../ preservation as a follow-up only if embedded/iframe use-cases can supply ../... as attrs.src (add a test if so).

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/react-router/src/Asset.tsx` around lines 142 - 144, The current
Asset.tsx logic preserves only relative src values that start with "./" but not
"../"; update the code by keeping the existing behavior (do not add preservation
for "../" paths) and add a concise inline comment near the attrs.src handling
(in the Asset component / function that checks attrs.src.startsWith('./'))
stating why "../" is deliberately not preserved and that "../" should only be
added later if a real input source can produce it (with a test at that time); do
not change normalization via new URL(attrs.src, base).href now.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/react-router/src/Asset.tsx`:
- Around line 142-144: The current Asset.tsx logic preserves only relative src
values that start with "./" but not "../"; update the code by keeping the
existing behavior (do not add preservation for "../" paths) and add a concise
inline comment near the attrs.src handling (in the Asset component / function
that checks attrs.src.startsWith('./')) stating why "../" is deliberately not
preserved and that "../" should only be added later if a real input source can
produce it (with a test at that time); do not change normalization via new
URL(attrs.src, base).href now.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: be0d6972-badd-43dc-bcb2-b4a75599958a

📥 Commits

Reviewing files that changed from the base of the PR and between 757d433 and 2308966.

📒 Files selected for processing (2)

• packages/react-router/src/Asset.tsx
• packages/start-plugin-core/src/start-manifest-plugin/manifestBuilder.ts