Feature: hook to transform asset/data URLs at SSR (for version-skew protection on Vercel et al.)

[ap-justin]

Summary

React Router framework mode lacks a hook to transform asset and single-fetch URLs at SSR time. This blocks platforms (Vercel, Netlify, etc.) from implementing version-skew protection the way Next.js, SvelteKit, Astro, Qwik, and Nuxt do — by suffixing a deployment id (e.g. ?dpl=<id>) onto every framework-managed client request so stale HTML still resolves its content-hashed chunks after a new deploy.

Related downstream issue: vercel/vercel#16604 — @vercel/react-router can't implement automatic skew protection without a framework-level hook.

Background

When a CDN-cached HTML response references content-hashed assets (/assets/chunk-abc123.js), and a new deploy ships, returning users load the stale HTML and request chunks that no longer exist in the new deployment. The result is a wave of 404s — each hitting the SSR function on Vercel — every deploy.

Supported frameworks solve this by injecting ?dpl=<VERCEL_DEPLOYMENT_ID> (read from env at SSR) into:

• <script> / <link> URLs in the rendered HTML
• the client manifest URL
• single-fetch .data loader requests
• prefetch link URLs

Vercel's edge reads the param and routes the request to the matching deployment. See Vercel — Skew Protection.

The Vercel docs list React Router as not automatically supported. The documented workaround is setting a __vdpl cookie in entry.server.tsx, but Set-Cookie makes the HTML response uncacheable on Vercel's CDN — forcing apps to choose between CDN cache and skew protection. The query-param mechanism used by other frameworks avoids the tradeoff.

Proposal

Add a public API for transforming framework-managed URLs at SSR time. Two reasonable shapes:

Option A — entry.server export

// app/entry.server.tsx
export function transformAssetUrl(url: string): string {
  const dpl = process.env.VERCEL_DEPLOYMENT_ID;
  return dpl ? `${url}${url.includes('?') ? '&' : '?'}dpl=${dpl}` : url;
}

Called once per URL when <Scripts> / <Links> / useFetcher / single-fetch builds a framework-managed URL. Covers:

• manifest.url
• manifest.entry.module and imports
• per-route module, imports, css, client*Module, hydrateFallbackModule
• the ${pathname}.data URL constructed for single-fetch loader requests
• PrefetchPageLinks hrefs

The result must be serialized into __remixManifest / __remixContext so client-side navigation also uses transformed URLs.

Option B — config in react-router.config.ts

export default {
  ssr: true,
  assetUrlTransform: (url) =>
    process.env.VERCEL_DEPLOYMENT_ID
      ? `${url}?dpl=${process.env.VERCEL_DEPLOYMENT_ID}`
      : url,
} satisfies Config;

A is more flexible (per-request access if signature accepts request). B is more declarative.

Why a framework hook is the right layer

• The manifest is built by @react-router/dev and consumed by <Scripts> / <Links> / single-fetch — none of which today expose a transform seam.
• Userland workarounds either mutate the (untyped, UNSAFE_*) shared manifest object in entry.server (fragile across RR versions) or stream-rewrite the rendered HTML (chunk-boundary hazards, can't reach __remixManifest consistently, and doesn't cover .data requests).
• Adapter packages (@vercel/react-router) can't implement this cleanly without a framework hook either — they'd have to fork or patch RR internals. See vercel/vercel#16604.

Once the hook exists, the Vercel preset (and equivalents for other hosts) becomes a one-liner that reads VERCEL_DEPLOYMENT_ID and wires the transform.

Scope of "framework-managed" URLs

• ✅ Asset URLs from the manifest (entry + per-route)
• ✅ The manifest URL itself
• ✅ Single-fetch .data URLs
• ✅ PrefetchPageLinks hrefs
• ❌ User-authored <a href> / <Link to> — these are app concerns, not framework

Alternatives considered

1. Cookie-based pinning (__vdpl) — what the Vercel docs recommend today; kills CDN cache on every SSR'd response.
2. Mutate EntryContext.manifest in entry.server — works but uses UNSAFE_AssetsManifest types and a shared object reference; breaks silently on schema changes.
3. HTML stream rewrite — chunk-boundary hazards, misses __remixManifest, doesn't cover .data.

A first-class hook is the only durable answer.

Prior art

• Next.js: reads process.env.NEXT_DEPLOYMENT_ID and appends ?dpl= framework-wide.
• SvelteKit: config.kit.version.pollInterval + automatic asset URL pinning when version.name is set.
• Astro / Qwik / Nuxt: similar built-in mechanisms.

Happy to draft an RFC / PR if there's interest in either shape.

---

🤖 Filed by Claude on behalf of @ap-justin

[brophdawg11]

Converted to a discussion according to the Open Governance model