@tanstack/start-server-core 1.158.3 → 1.159.0

package/dist/esm/transformAssetUrls.js

@@ -0,0 +1,113 @@
+import { rootRouteId } from "@tanstack/router-core";
+function resolveTransformConfig(transform) {
+  if (typeof transform === "string") {
+    const prefix = transform;
+    return {
+      type: "transform",
+      transformFn: ({ url }) => `${prefix}${url}`,
+      cache: true
+    };
+  }
+  if (typeof transform === "function") {
+    return {
+      type: "transform",
+      transformFn: transform,
+      cache: true
+    };
+  }
+  if ("createTransform" in transform && transform.createTransform) {
+    return {
+      type: "createTransform",
+      createTransform: transform.createTransform,
+      cache: transform.cache !== false
+    };
+  }
+  const transformFn = typeof transform.transform === "string" ? (({ url }) => `${transform.transform}${url}`) : transform.transform;
+  return {
+    type: "transform",
+    transformFn,
+    cache: transform.cache !== false
+  };
+}
+function buildClientEntryScriptTag(clientEntry, injectedHeadScripts) {
+  const clientEntryLiteral = JSON.stringify(clientEntry);
+  let script = `import(${clientEntryLiteral})`;
+  if (injectedHeadScripts) {
+    script = `${injectedHeadScripts};${script}`;
+  }
+  return {
+    tag: "script",
+    attrs: {
+      type: "module",
+      async: true
+    },
+    children: script
+  };
+}
+function transformManifestUrls(source, transformFn, opts) {
+  return (async () => {
+    const manifest = opts?.clone ? structuredClone(source.manifest) : source.manifest;
+    for (const route of Object.values(manifest.routes)) {
+      if (route.preloads) {
+        route.preloads = await Promise.all(
+          route.preloads.map(
+            (url) => Promise.resolve(transformFn({ url, type: "modulepreload" }))
+          )
+        );
+      }
+      if (route.assets) {
+        for (const asset of route.assets) {
+          if (asset.tag === "link" && asset.attrs?.href) {
+            asset.attrs.href = await Promise.resolve(
+              transformFn({
+                url: asset.attrs.href,
+                type: "stylesheet"
+              })
+            );
+          }
+        }
+      }
+    }
+    const transformedClientEntry = await Promise.resolve(
+      transformFn({
+        url: source.clientEntry,
+        type: "clientEntry"
+      })
+    );
+    const rootRoute = manifest.routes[rootRouteId];
+    if (rootRoute) {
+      rootRoute.assets = rootRoute.assets || [];
+      rootRoute.assets.push(
+        buildClientEntryScriptTag(
+          transformedClientEntry,
+          source.injectedHeadScripts
+        )
+      );
+    }
+    return manifest;
+  })();
+}
+function buildManifestWithClientEntry(source) {
+  const scriptTag = buildClientEntryScriptTag(
+    source.clientEntry,
+    source.injectedHeadScripts
+  );
+  const baseRootRoute = source.manifest.routes[rootRouteId];
+  const routes = {
+    ...source.manifest.routes,
+    ...baseRootRoute ? {
+      [rootRouteId]: {
+        ...baseRootRoute,
+        assets: [...baseRootRoute.assets || [], scriptTag]
+      }
+    } : {}
+  };
+  return { routes };
+}
+export {
+  buildClientEntryScriptTag,
+  buildManifestWithClientEntry,
+  resolveTransformConfig,
+  transformManifestUrls
+};
+//# sourceMappingURL=transformAssetUrls.js.map

package/dist/esm/transformAssetUrls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformAssetUrls.js","sources":["../../src/transformAssetUrls.ts"],"sourcesContent":["import { rootRouteId } from '@tanstack/router-core'\n\nimport type {\n  Awaitable,\n  Manifest,\n  RouterManagedTag,\n} from '@tanstack/router-core'\n\nexport type AssetUrlType = 'modulepreload' | 'stylesheet' | 'clientEntry'\n\nexport interface TransformAssetUrlsContext {\n  url: string\n  type: AssetUrlType\n}\n\nexport type TransformAssetUrlsFn = (\n  context: TransformAssetUrlsContext,\n) => Awaitable<string>\n\nexport type CreateTransformAssetUrlsContext =\n  | {\n      /** True when the server is computing the cached manifest during startup warmup. */\n      warmup: true\n    }\n  | {\n      /**\n       * The current Request.\n       *\n       * Only available during request handling (i.e. when `warmup: false`).\n       */\n      request: Request\n      /** False when transforming URLs as part of request handling. */\n      warmup: false\n    }\n\n/**\n * Async factory that runs once per manifest computation and returns the\n * per-asset transform.\n */\nexport type CreateTransformAssetUrlsFn = (\n  ctx: CreateTransformAssetUrlsContext,\n) => Awaitable<TransformAssetUrlsFn>\n\ntype TransformAssetUrlsOptionsBase = {\n  /**\n   * Whether to cache the transformed manifest after the first request.\n   *\n   * When `true` (default), the transform runs once on the first request and\n   * the resulting manifest is reused for all subsequent requests in production.\n   *\n   * Set to `false` for per-request transforms (e.g. geo-routing to different\n   * CDNs based on request headers).\n   *\n   * @default true\n   */\n  cache?: boolean\n\n  /**\n   * When `true`, warms up the cached transformed manifest in the background when\n   * the server starts (production only).\n   *\n   * This can reduce latency for the first request when `cache` is `true`.\n   * Has no effect when `cache: false` (per-request transforms) or in dev mode.\n   *\n   * @default false\n   */\n  warmup?: boolean\n}\n\nexport type TransformAssetUrlsOptions =\n  | (TransformAssetUrlsOptionsBase & {\n      /**\n       * The transform to apply to asset URLs. Can be a string prefix or a callback.\n       *\n       * **String** — prepended to every asset URL.\n       * **Callback** — receives `{ url, type }` and returns a new URL.\n       */\n      transform: string | TransformAssetUrlsFn\n      createTransform?: never\n    })\n  | (TransformAssetUrlsOptionsBase & {\n      /**\n       * Create a per-asset transform function.\n       *\n       * This factory runs once per manifest computation (per request when\n       * `cache: false`, or once per server when `cache: true`). It can do async\n       * setup work (fetch config, read from a KV, etc.) and return a fast\n       * per-asset transformer.\n       */\n      createTransform: CreateTransformAssetUrlsFn\n      transform?: never\n    })\n\nexport type TransformAssetUrls =\n  | string\n  | TransformAssetUrlsFn\n  | TransformAssetUrlsOptions\n\nexport type ResolvedTransformAssetUrlsConfig =\n  | {\n      type: 'transform'\n      transformFn: TransformAssetUrlsFn\n      cache: boolean\n    }\n  | {\n      type: 'createTransform'\n      createTransform: CreateTransformAssetUrlsFn\n      cache: boolean\n    }\n\n/**\n * Resolves a TransformAssetUrls value (string prefix, callback, or options\n * object) into a concrete transform function and cache flag.\n */\nexport function resolveTransformConfig(\n  transform: TransformAssetUrls,\n): ResolvedTransformAssetUrlsConfig {\n  // String shorthand\n  if (typeof transform === 'string') {\n    const prefix = transform\n    return {\n      type: 'transform',\n      transformFn: ({ url }) => `${prefix}${url}`,\n      cache: true,\n    }\n  }\n\n  // Callback shorthand\n  if (typeof transform === 'function') {\n    return {\n      type: 'transform',\n      transformFn: transform,\n      cache: true,\n    }\n  }\n\n  // Options object\n  if ('createTransform' in transform && transform.createTransform) {\n    return {\n      type: 'createTransform',\n      createTransform: transform.createTransform,\n      cache: transform.cache !== false,\n    }\n  }\n\n  const transformFn =\n    typeof transform.transform === 'string'\n      ? ((({ url }: TransformAssetUrlsContext) =>\n          `${transform.transform}${url}`) as TransformAssetUrlsFn)\n      : transform.transform\n\n  return {\n    type: 'transform',\n    transformFn,\n    cache: transform.cache !== false,\n  }\n}\n\nexport interface StartManifestWithClientEntry {\n  manifest: Manifest\n  clientEntry: string\n  /** Script content prepended before the client entry import (dev only) */\n  injectedHeadScripts?: string\n}\n\n/**\n * Builds the client entry `<script>` tag from a (possibly transformed) client\n * entry URL and optional injected head scripts.\n */\nexport function buildClientEntryScriptTag(\n  clientEntry: string,\n  injectedHeadScripts?: string,\n): RouterManagedTag {\n  const clientEntryLiteral = JSON.stringify(clientEntry)\n  let script = `import(${clientEntryLiteral})`\n  if (injectedHeadScripts) {\n    script = `${injectedHeadScripts};${script}`\n  }\n  return {\n    tag: 'script',\n    attrs: {\n      type: 'module',\n      async: true,\n    },\n    children: script,\n  }\n}\n\n/**\n * Applies a URL transform to every asset URL in the manifest and returns a\n * new manifest with a client entry script tag appended to the root route's\n * assets.\n *\n * The source manifest is deep-cloned so the cached original is never mutated.\n */\nexport function transformManifestUrls(\n  source: StartManifestWithClientEntry,\n  transformFn: TransformAssetUrlsFn,\n  opts?: {\n    /** When true, clone the source manifest before mutating it. */\n    clone?: boolean\n  },\n): Promise<Manifest> {\n  return (async () => {\n    const manifest = opts?.clone\n      ? structuredClone(source.manifest)\n      : source.manifest\n\n    for (const route of Object.values(manifest.routes)) {\n      // Transform preload URLs (modulepreload)\n      if (route.preloads) {\n        route.preloads = await Promise.all(\n          route.preloads.map((url) =>\n            Promise.resolve(transformFn({ url, type: 'modulepreload' })),\n          ),\n        )\n      }\n\n      // Transform asset tag URLs\n      if (route.assets) {\n        for (const asset of route.assets) {\n          if (asset.tag === 'link' && asset.attrs?.href) {\n            asset.attrs.href = await Promise.resolve(\n              transformFn({\n                url: asset.attrs.href,\n                type: 'stylesheet',\n              }),\n            )\n          }\n        }\n      }\n    }\n\n    // Transform and append the client entry script tag\n    const transformedClientEntry = await Promise.resolve(\n      transformFn({\n        url: source.clientEntry,\n        type: 'clientEntry',\n      }),\n    )\n\n    const rootRoute = manifest.routes[rootRouteId]\n    if (rootRoute) {\n      rootRoute.assets = rootRoute.assets || []\n      rootRoute.assets.push(\n        buildClientEntryScriptTag(\n          transformedClientEntry,\n          source.injectedHeadScripts,\n        ),\n      )\n    }\n\n    return manifest\n  })()\n}\n\n/**\n * Builds a final Manifest from a StartManifestWithClientEntry without any\n * URL transforms. Used when no transformAssetUrls option is provided.\n *\n * Returns a new manifest object so the cached base manifest is never mutated.\n */\nexport function buildManifestWithClientEntry(\n  source: StartManifestWithClientEntry,\n): Manifest {\n  const scriptTag = buildClientEntryScriptTag(\n    source.clientEntry,\n    source.injectedHeadScripts,\n  )\n\n  const baseRootRoute = source.manifest.routes[rootRouteId]\n  const routes = {\n    ...source.manifest.routes,\n    ...(baseRootRoute\n      ? {\n          [rootRouteId]: {\n            ...baseRootRoute,\n            assets: [...(baseRootRoute.assets || []), scriptTag],\n          },\n        }\n      : {}),\n  }\n\n  return { routes }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/start-server-core",
-  "version": "1.158.3",
+  "version": "1.159.0",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -64,9 +64,9 @@
     "seroval": "^1.4.2",
     "tiny-invariant": "^1.3.3",
     "@tanstack/history": "1.154.14",
-    "@tanstack/start-storage-context": "1.158.1",
-    "@tanstack/router-core": "1.158.1",
-    "@tanstack/start-client-core": "1.158.3"
+    "@tanstack/router-core": "1.158.4",
+    "@tanstack/start-client-core": "1.158.4",
+    "@tanstack/start-storage-context": "1.158.4"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.0.0",

package/src/createStartHandler.ts

@@ -19,6 +19,11 @@ import { runWithStartContext } from '@tanstack/start-storage-context'
 import { requestHandler } from './request-response'
 import { getStartManifest } from './router-manifest'
 import { handleServerAction } from './server-functions-handler'
+import {
+  buildManifestWithClientEntry,
+  resolveTransformConfig,
+  transformManifestUrls,
+} from './transformAssetUrls'
 
 import { HEADERS } from './constants'
 import { ServerFunctionSerializationAdapter } from './serializer/ServerFunctionSerializationAdapter'
@@ -39,6 +44,11 @@ import type {
   Register,
 } from '@tanstack/router-core'
 import type { HandlerCallback } from '@tanstack/router-core/ssr/server'
+import type {
+  StartManifestWithClientEntry,
+  TransformAssetUrls,
+  TransformAssetUrlsFn,
+} from './transformAssetUrls'
 
 type TODO = any
 
@@ -46,6 +56,61 @@ type AnyMiddlewareServerFn =
   | AnyRequestMiddleware['options']['server']
   | AnyFunctionMiddleware['options']['server']
 
+export interface CreateStartHandlerOptions {
+  handler: HandlerCallback<AnyRouter>
+  /**
+   * Transform asset URLs at runtime, e.g. to prepend a CDN prefix.
+   *
+   * **String** — a URL prefix prepended to every asset URL (cached by default):
+   * ```ts
+   * createStartHandler({
+   *   handler: defaultStreamHandler,
+   *   transformAssetUrls: 'https://cdn.example.com',
+   * })
+   * ```
+   *
+   * **Callback** — receives `{ url, type }` and returns a new URL
+   * (cached by default — runs once on first request):
+   * ```ts
+   * createStartHandler({
+   *   handler: defaultStreamHandler,
+   *   transformAssetUrls: ({ url, type }) => {
+   *     return `https://cdn.example.com${url}`
+   *   },
+   * })
+   * ```
+   *
+   * **Object** — for explicit cache control:
+   * ```ts
+   * createStartHandler({
+   *   handler: defaultStreamHandler,
+   *   transformAssetUrls: {
+   *     transform: ({ url }) => {
+   *       const region = getRequest().headers.get('x-region') || 'us'
+   *       return `https://cdn-${region}.example.com${url}`
+   *     },
+   *     cache: false, // transform per-request
+   *   },
+   * })
+   * ```
+   *
+   * `type` is one of `'modulepreload' | 'stylesheet' | 'clientEntry'`.
+   *
+   * By default, the transformed manifest is cached after the first request
+   * (`cache: true`). Set `cache: false` for per-request transforms.
+   *
+   * If you're using a cached transform, you can optionally set `warmup: true`
+   * (object form only) to compute the transformed manifest in the background at
+   * server startup.
+   *
+   * Note: This only transforms URLs managed by TanStack Start's manifest
+   * (JS preloads, CSS links, and the client entry script). For asset imports
+   * used directly in components (e.g. `import logo from './logo.svg'`),
+   * configure Vite's `experimental.renderBuiltUrl` in your vite.config.ts.
+   */
+  transformAssetUrls?: TransformAssetUrls
+}
+
 function getStartResponseHeaders(opts: { router: AnyRouter }) {
   const headers = mergeHeaders(
     {
@@ -66,7 +131,13 @@ let entriesPromise:
       routerEntry: RouterEntry
     }>
   | undefined
-let manifestPromise: Promise<Manifest> | undefined
+let baseManifestPromise: Promise<StartManifestWithClientEntry> | undefined
+
+/**
+ * Cached final manifest (with client entry script tag). In production,
+ * this is computed once and reused for every request when caching is enabled.
+ */
+let cachedFinalManifestPromise: Promise<Manifest> | undefined
 
 async function loadEntries() {
   // @ts-ignore when building, we currently don't respect tsconfig.ts' `include` so we are not picking up the .d.ts from start-client-core
@@ -83,16 +154,59 @@ function getEntries() {
   return entriesPromise
 }
 
-function getManifest(matchedRoutes?: ReadonlyArray<AnyRoute>) {
+/**
+ * Returns the raw manifest data (without client entry script tag baked in).
+ * In dev mode, always returns fresh data. In prod, cached.
+ */
+function getBaseManifest(
+  matchedRoutes?: ReadonlyArray<AnyRoute>,
+): Promise<StartManifestWithClientEntry> {
   // In dev mode, always get fresh manifest (no caching) to include route-specific dev styles
   if (process.env.TSS_DEV_SERVER === 'true') {
     return getStartManifest(matchedRoutes)
   }
-  // In prod, cache the manifest
-  if (!manifestPromise) {
-    manifestPromise = getStartManifest()
+  // In prod, cache the base manifest
+  if (!baseManifestPromise) {
+    baseManifestPromise = getStartManifest()
   }
-  return manifestPromise
+  return baseManifestPromise
+}
+
+/**
+ * Resolves a final Manifest for a given request.
+ *
+ * - No transform: builds client entry script tag and returns (cached in prod).
+ * - Cached transform: transforms all URLs + builds script tag, caches result.
+ * - Per-request transform: deep-clones base manifest, transforms per-request.
+ */
+async function resolveManifest(
+  matchedRoutes: ReadonlyArray<AnyRoute> | undefined,
+  transformFn: TransformAssetUrlsFn | undefined,
+  cache: boolean,
+): Promise<Manifest> {
+  const base = await getBaseManifest(matchedRoutes)
+
+  const computeFinalManifest = async () => {
+    return transformFn
+      ? await transformManifestUrls(base, transformFn, { clone: !cache })
+      : buildManifestWithClientEntry(base)
+  }
+
+  // In dev, always compute fresh to include route-specific dev styles.
+  if (process.env.TSS_DEV_SERVER === 'true') {
+    return computeFinalManifest()
+  }
+
+  // In prod, cache unless we're explicitly doing per-request transforms.
+  if (!transformFn || cache) {
+    if (!cachedFinalManifestPromise) {
+      cachedFinalManifestPromise = computeFinalManifest()
+    }
+    return cachedFinalManifestPromise
+  }
+
+  // Per-request transform — deep-clone and transform every time.
+  return computeFinalManifest()
 }
 
 // Pre-computed constants
@@ -206,9 +320,107 @@ function handlerToMiddleware(
   }
 }
 
+/**
+ * Creates the TanStack Start request handler.
+ *
+ * @example Backwards-compatible usage (handler callback only):
+ * ```ts
+ * export default createStartHandler(defaultStreamHandler)
+ * ```
+ *
+ * @example With CDN URL rewriting:
+ * ```ts
+ * export default createStartHandler({
+ *   handler: defaultStreamHandler,
+ *   transformAssetUrls: 'https://cdn.example.com',
+ * })
+ * ```
+ *
+ * @example With per-request URL rewriting:
+ * ```ts
+ * export default createStartHandler({
+ *   handler: defaultStreamHandler,
+ *   transformAssetUrls: {
+ *     transform: ({ url }) => {
+ *       const cdnBase = getRequest().headers.get('x-cdn-base') || ''
+ *       return `${cdnBase}${url}`
+ *     },
+ *     cache: false,
+ *   },
+ * })
+ * ```
+ */
 export function createStartHandler<TRegister = Register>(
-  cb: HandlerCallback<AnyRouter>,
+  cbOrOptions: HandlerCallback<AnyRouter> | CreateStartHandlerOptions,
 ): RequestHandler<TRegister> {
+  // Normalize the overloaded argument
+  const cb: HandlerCallback<AnyRouter> =
+    typeof cbOrOptions === 'function' ? cbOrOptions : cbOrOptions.handler
+  const transformAssetUrlsOption: TransformAssetUrls | undefined =
+    typeof cbOrOptions === 'function'
+      ? undefined
+      : cbOrOptions.transformAssetUrls
+
+  const warmupTransformManifest =
+    !!transformAssetUrlsOption &&
+    typeof transformAssetUrlsOption === 'object' &&
+    transformAssetUrlsOption.warmup === true
+
+  // Pre-resolve the transform function and cache flag
+  const resolvedTransformConfig = transformAssetUrlsOption
+    ? resolveTransformConfig(transformAssetUrlsOption)
+    : undefined
+  const cache = resolvedTransformConfig ? resolvedTransformConfig.cache : true
+
+  // Memoize a single createTransform() result when caching is enabled.
+  let cachedCreateTransformPromise: Promise<TransformAssetUrlsFn> | undefined
+
+  const getTransformFn = async (
+    opts: { warmup: true } | { warmup: false; request: Request },
+  ): Promise<TransformAssetUrlsFn | undefined> => {
+    if (!resolvedTransformConfig) return undefined
+    if (resolvedTransformConfig.type === 'createTransform') {
+      if (cache) {
+        if (!cachedCreateTransformPromise) {
+          cachedCreateTransformPromise = Promise.resolve(
+            resolvedTransformConfig.createTransform(opts),
+          )
+        }
+        return cachedCreateTransformPromise
+      }
+      return resolvedTransformConfig.createTransform(opts)
+    }
+    return resolvedTransformConfig.transformFn
+  }
+
+  // Background warmup for cached transforms (production only)
+  if (
+    warmupTransformManifest &&
+    cache &&
+    process.env.TSS_DEV_SERVER !== 'true' &&
+    !cachedFinalManifestPromise
+  ) {
+    // NOTE: Do not call resolveManifest() here.
+    // resolveManifest() reads from cachedFinalManifestPromise, and since we set
+    // cachedFinalManifestPromise to this warmup promise, that would create a
+    // self-referential promise and hang forever.
+    const warmupPromise = (async () => {
+      const base = await getBaseManifest(undefined)
+      const transformFn = await getTransformFn({ warmup: true })
+      return transformFn
+        ? await transformManifestUrls(base, transformFn, { clone: false })
+        : buildManifestWithClientEntry(base)
+    })()
+    cachedFinalManifestPromise = warmupPromise
+    warmupPromise.catch(() => {
+      // If warmup fails, allow the next request to retry.
+      if (cachedFinalManifestPromise === warmupPromise) {
+        cachedFinalManifestPromise = undefined
+      }
+      cachedCreateTransformPromise = undefined
+    })
+  }
+
   const startRequestResolver: RequestHandler<Register> = async (
     request,
     requestOpts,
@@ -218,10 +430,16 @@ export function createStartHandler<TRegister = Register>(
 
     try {
       // normalizing and sanitizing the pathname here for server, so we always deal with the same format during SSR.
-      const url = getNormalizedURL(request.url)
+      // during normalization paths like '//posts' are flattened to '/posts'.
+      // in these cases we would prefer to redirect to the new path
+      const { url, handledProtocolRelativeURL } = getNormalizedURL(request.url)
       const href = url.pathname + url.search + url.hash
       const origin = getOrigin(request)
 
+      if (handledProtocolRelativeURL) {
+        return Response.redirect(url, 308)
+      }
+
       const entries = await getEntries()
       const startOptions: AnyStartInstanceOptions =
         (await entries.startEntry.startInstance?.getOptions()) ||
@@ -339,7 +557,11 @@ export function createStartHandler<TRegister = Register>(
           )
         }
 
-        const manifest = await getManifest(matchedRoutes)
+        const manifest = await resolveManifest(
+          matchedRoutes,
+          await getTransformFn({ warmup: false, request }),
+          cache,
+        )
         const routerInstance = await getRouter()
 
         attachRouterServerSsrUtils({

package/src/index.tsx

@@ -1,4 +1,13 @@
 export { createStartHandler } from './createStartHandler'
+export type { CreateStartHandlerOptions } from './createStartHandler'
+
+export type {
+  TransformAssetUrls,
+  TransformAssetUrlsFn,
+  TransformAssetUrlsContext,
+  TransformAssetUrlsOptions,
+  AssetUrlType,
+} from './transformAssetUrls'
 
 export {
   attachRouterServerSsrUtils,

package/src/router-manifest.ts

@@ -1,21 +1,25 @@
 import { buildDevStylesUrl, rootRouteId } from '@tanstack/router-core'
 import type { AnyRoute, RouterManagedTag } from '@tanstack/router-core'
+import type { StartManifestWithClientEntry } from './transformAssetUrls'
 
 // Pre-computed constant for dev styles URL
 const ROUTER_BASEPATH = process.env.TSS_ROUTER_BASEPATH || '/'
 
 /**
- * @description Returns the router manifest that should be sent to the client.
+ * @description Returns the router manifest data that should be sent to the client.
  * This includes only the assets and preloads for the current route and any
  * special assets that are needed for the client. It does not include relationships
  * between routes or any other data that is not needed for the client.
  *
+ * The client entry URL is returned separately so that it can be transformed
+ * (e.g. for CDN rewriting) before being embedded into the `<script>` tag.
+ *
  * @param matchedRoutes - In dev mode, the matched routes are used to build
  * the dev styles URL for route-scoped CSS collection.
  */
 export async function getStartManifest(
   matchedRoutes?: ReadonlyArray<AnyRoute>,
-) {
+): Promise<StartManifestWithClientEntry> {
   const { tsrStartManifest } = await import('tanstack-start-manifest:v')
   const startManifest = tsrStartManifest()
 
@@ -37,22 +41,15 @@ export async function getStartManifest(
     })
   }
 
-  let script = `import('${startManifest.clientEntry}')`
+  // Collect injected head scripts in dev mode (returned separately so we can
+  // build the client entry script tag after URL transforms are applied)
+  let injectedHeadScripts: string | undefined
   if (process.env.TSS_DEV_SERVER === 'true') {
-    const { injectedHeadScripts } =
-      await import('tanstack-start-injected-head-scripts:v')
-    if (injectedHeadScripts) {
-      script = `${injectedHeadScripts + ';'}${script}`
+    const mod = await import('tanstack-start-injected-head-scripts:v')
+    if (mod.injectedHeadScripts) {
+      injectedHeadScripts = mod.injectedHeadScripts
     }
   }
-  rootRoute.assets.push({
-    tag: 'script',
-    attrs: {
-      type: 'module',
-      async: true,
-    },
-    children: script,
-  })
 
   const manifest = {
     routes: Object.fromEntries(
@@ -78,6 +75,9 @@ export async function getStartManifest(
     ),
   }
 
-  // Strip out anything that isn't needed for the client
-  return manifest
+  return {
+    manifest,
+    clientEntry: startManifest.clientEntry,
+    injectedHeadScripts,
+  }
 }