@tanstack/start-server-core 1.167.2 → 1.167.4

package/dist/esm/transformAssetUrls.js

@@ -1,15 +1,30 @@
-import { rootRouteId } from "@tanstack/router-core";
+import { resolveManifestAssetLink, rootRouteId } from "@tanstack/router-core";
 //#region src/transformAssetUrls.ts
-/**
-* Resolves a TransformAssetUrls value (string prefix, callback, or options
-* object) into a concrete transform function and cache flag.
-*/
-function resolveTransformConfig(transform) {
+var hasWarnedAboutDeprecatedTransformAssetUrls = false;
+function warnDeprecatedTransformAssetUrls() {
+	if ((process.env.NODE_ENV === "development" || process.env.TSS_DEV_SERVER === "true") && !hasWarnedAboutDeprecatedTransformAssetUrls) {
+		hasWarnedAboutDeprecatedTransformAssetUrls = true;
+		console.warn("[TanStack Start] `transformAssetUrls` is deprecated. Use `transformAssets` instead.");
+	}
+}
+function normalizeTransformAssetResult(result) {
+	if (typeof result === "string") return { href: result };
+	return result;
+}
+function resolveTransformAssetsCrossOrigin(config, kind) {
+	if (!config) return void 0;
+	if (typeof config === "string") return config;
+	return config[kind];
+}
+function isObjectShorthand(transform) {
+	return "prefix" in transform;
+}
+function resolveTransformAssetsConfig(transform) {
 	if (typeof transform === "string") {
 		const prefix = transform;
 		return {
 			type: "transform",
-			transformFn: ({ url }) => `${prefix}${url}`,
+			transformFn: ({ url }) => ({ href: `${prefix}${url}` }),
 			cache: true
 		};
 	}
@@ -18,6 +33,22 @@ function resolveTransformConfig(transform) {
 		transformFn: transform,
 		cache: true
 	};
+	if (isObjectShorthand(transform)) {
+		const { prefix, crossOrigin } = transform;
+		return {
+			type: "transform",
+			transformFn: ({ url, kind }) => {
+				const href = `${prefix}${url}`;
+				if (kind === "clientEntry") return { href };
+				const co = resolveTransformAssetsCrossOrigin(crossOrigin, kind);
+				return co ? {
+					href,
+					crossOrigin: co
+				} : { href };
+			},
+			cache: true
+		};
+	}
 	if ("createTransform" in transform && transform.createTransform) return {
 		type: "createTransform",
 		createTransform: transform.createTransform,
@@ -25,10 +56,31 @@ function resolveTransformConfig(transform) {
 	};
 	return {
 		type: "transform",
-		transformFn: typeof transform.transform === "string" ? (({ url }) => `${transform.transform}${url}`) : transform.transform,
+		transformFn: typeof transform.transform === "string" ? (({ url }) => ({ href: `${transform.transform}${url}` })) : transform.transform,
 		cache: transform.cache !== false
 	};
 }
+function adaptTransformAssetUrlsToTransformAssets(transformFn) {
+	return async ({ url, kind }) => ({ href: await transformFn({
+		url,
+		type: kind
+	}) });
+}
+function adaptTransformAssetUrlsConfigToTransformAssets(transform) {
+	warnDeprecatedTransformAssetUrls();
+	if (typeof transform === "string") return transform;
+	if (typeof transform === "function") return adaptTransformAssetUrlsToTransformAssets(transform);
+	if ("createTransform" in transform && transform.createTransform) return {
+		createTransform: async (ctx) => adaptTransformAssetUrlsToTransformAssets(await transform.createTransform(ctx)),
+		cache: transform.cache,
+		warmup: transform.warmup
+	};
+	return {
+		transform: typeof transform.transform === "string" ? transform.transform : adaptTransformAssetUrlsToTransformAssets(transform.transform),
+		cache: transform.cache,
+		warmup: transform.warmup
+	};
+}
 /**
 * Builds the client entry `<script>` tag from a (possibly transformed) client
 * entry URL and optional injected head scripts.
@@ -45,39 +97,47 @@ function buildClientEntryScriptTag(clientEntry, injectedHeadScripts) {
 		children: script
 	};
 }
-/**
-* Applies a URL transform to every asset URL in the manifest and returns a
-* new manifest with a client entry script tag appended to the root route's
-* assets.
-*
-* The source manifest is deep-cloned so the cached original is never mutated.
-*/
-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({
+function assignManifestAssetLink(link, next) {
+	if (typeof link === "string") return next.crossOrigin ? next : next.href;
+	return next.crossOrigin ? next : { href: next.href };
+}
+async function transformManifestAssets(source, transformFn, _opts) {
+	const manifest = structuredClone(source.manifest);
+	for (const route of Object.values(manifest.routes)) {
+		if (route.preloads) route.preloads = await Promise.all(route.preloads.map(async (link) => {
+			const result = normalizeTransformAssetResult(await transformFn({
+				url: resolveManifestAssetLink(link).href,
+				kind: "modulepreload"
+			}));
+			return assignManifestAssetLink(link, {
+				href: result.href,
+				crossOrigin: result.crossOrigin
+			});
+		}));
+		if (route.assets) {
+			for (const asset of route.assets) if (asset.tag === "link" && asset.attrs?.href) {
+				const rel = asset.attrs.rel;
+				if (!(typeof rel === "string" ? rel.split(/\s+/) : []).includes("stylesheet")) continue;
+				const result = normalizeTransformAssetResult(await transformFn({
 					url: asset.attrs.href,
-					type: "stylesheet"
+					kind: "stylesheet"
 				}));
+				asset.attrs.href = result.href;
+				if (result.crossOrigin) asset.attrs.crossOrigin = result.crossOrigin;
+				else delete asset.attrs.crossOrigin;
 			}
 		}
-		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;
-	})();
+	}
+	const transformedClientEntry = normalizeTransformAssetResult(await transformFn({
+		url: source.clientEntry,
+		kind: "clientEntry"
+	}));
+	const rootRoute = manifest.routes[rootRouteId];
+	if (rootRoute) {
+		rootRoute.assets = rootRoute.assets || [];
+		rootRoute.assets.push(buildClientEntryScriptTag(transformedClientEntry.href, source.injectedHeadScripts));
+	}
+	return manifest;
 }
 /**
 * Builds a final Manifest from a StartManifestWithClientEntry without any
@@ -97,6 +157,6 @@ function buildManifestWithClientEntry(source) {
 	} };
 }
 //#endregion
-export { buildManifestWithClientEntry, resolveTransformConfig, transformManifestUrls };
+export { adaptTransformAssetUrlsConfigToTransformAssets, buildManifestWithClientEntry, resolveTransformAssetsConfig, transformManifestAssets };
 
 //# sourceMappingURL=transformAssetUrls.js.map

package/dist/esm/transformAssetUrls.js.map

@@ -1 +1 @@
-{"version":3,"file":"transformAssetUrls.js","names":[],"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"],"mappings":";;;;;;AAkHA,SAAgB,uBACd,WACkC;AAElC,KAAI,OAAO,cAAc,UAAU;EACjC,MAAM,SAAS;AACf,SAAO;GACL,MAAM;GACN,cAAc,EAAE,UAAU,GAAG,SAAS;GACtC,OAAO;GACR;;AAIH,KAAI,OAAO,cAAc,WACvB,QAAO;EACL,MAAM;EACN,aAAa;EACb,OAAO;EACR;AAIH,KAAI,qBAAqB,aAAa,UAAU,gBAC9C,QAAO;EACL,MAAM;EACN,iBAAiB,UAAU;EAC3B,OAAO,UAAU,UAAU;EAC5B;AASH,QAAO;EACL,MAAM;EACN,aAPA,OAAO,UAAU,cAAc,aACxB,EAAE,UACH,GAAG,UAAU,YAAY,SAC3B,UAAU;EAKd,OAAO,UAAU,UAAU;EAC5B;;;;;;AAcH,SAAgB,0BACd,aACA,qBACkB;CAElB,IAAI,SAAS,UADc,KAAK,UAAU,YAAY,CACZ;AAC1C,KAAI,oBACF,UAAS,GAAG,oBAAoB,GAAG;AAErC,QAAO;EACL,KAAK;EACL,OAAO;GACL,MAAM;GACN,OAAO;GACR;EACD,UAAU;EACX;;;;;;;;;AAUH,SAAgB,sBACd,QACA,aACA,MAImB;AACnB,SAAQ,YAAY;EAClB,MAAM,WAAW,MAAM,QACnB,gBAAgB,OAAO,SAAS,GAChC,OAAO;AAEX,OAAK,MAAM,SAAS,OAAO,OAAO,SAAS,OAAO,EAAE;AAElD,OAAI,MAAM,SACR,OAAM,WAAW,MAAM,QAAQ,IAC7B,MAAM,SAAS,KAAK,QAClB,QAAQ,QAAQ,YAAY;IAAE;IAAK,MAAM;IAAiB,CAAC,CAAC,CAC7D,CACF;AAIH,OAAI,MAAM;SACH,MAAM,SAAS,MAAM,OACxB,KAAI,MAAM,QAAQ,UAAU,MAAM,OAAO,KACvC,OAAM,MAAM,OAAO,MAAM,QAAQ,QAC/B,YAAY;KACV,KAAK,MAAM,MAAM;KACjB,MAAM;KACP,CAAC,CACH;;;EAOT,MAAM,yBAAyB,MAAM,QAAQ,QAC3C,YAAY;GACV,KAAK,OAAO;GACZ,MAAM;GACP,CAAC,CACH;EAED,MAAM,YAAY,SAAS,OAAO;AAClC,MAAI,WAAW;AACb,aAAU,SAAS,UAAU,UAAU,EAAE;AACzC,aAAU,OAAO,KACf,0BACE,wBACA,OAAO,oBACR,CACF;;AAGH,SAAO;KACL;;;;;;;;AASN,SAAgB,6BACd,QACU;CACV,MAAM,YAAY,0BAChB,OAAO,aACP,OAAO,oBACR;CAED,MAAM,gBAAgB,OAAO,SAAS,OAAO;AAa7C,QAAO,EAAE,QAZM;EACb,GAAG,OAAO,SAAS;EACnB,GAAI,gBACA,GACG,cAAc;GACb,GAAG;GACH,QAAQ,CAAC,GAAI,cAAc,UAAU,EAAE,EAAG,UAAU;GACrD,EACF,GACD,EAAE;EACP,EAEgB"}
+{"version":3,"file":"transformAssetUrls.js","names":[],"sources":["../../src/transformAssetUrls.ts"],"sourcesContent":["import { resolveManifestAssetLink, rootRouteId } from '@tanstack/router-core'\n\nimport type {\n  AssetCrossOrigin,\n  Awaitable,\n  Manifest,\n  ManifestAssetLink,\n  RouterManagedTag,\n} from '@tanstack/router-core'\n\nexport type { AssetCrossOrigin }\n\nexport type TransformAssetKind = 'modulepreload' | 'stylesheet' | 'clientEntry'\n\ntype TransformAssetsShorthandCrossOriginKind = Exclude<\n  TransformAssetKind,\n  'clientEntry'\n>\n\nexport type AssetUrlType = TransformAssetKind\n\nexport interface TransformAssetsContext {\n  url: string\n  kind: TransformAssetKind\n}\n\nexport type TransformAssetResult =\n  | string\n  | {\n      href: string\n      crossOrigin?: AssetCrossOrigin\n    }\n\nexport type TransformAssetsFn = (\n  context: TransformAssetsContext,\n) => Awaitable<TransformAssetResult>\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\nexport type CreateTransformAssetsFn = (\n  ctx: CreateTransformAssetUrlsContext,\n) => Awaitable<TransformAssetsFn>\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 TransformAssetsOptions =\n  | (TransformAssetUrlsOptionsBase & {\n      transform: string | TransformAssetsFn\n      createTransform?: never\n    })\n  | (TransformAssetUrlsOptionsBase & {\n      createTransform: CreateTransformAssetsFn\n      transform?: never\n    })\n\nexport type TransformAssetUrls =\n  | string\n  | TransformAssetUrlsFn\n  | TransformAssetUrlsOptions\n\n/**\n * Per-kind crossOrigin configuration for the object shorthand.\n *\n * Accepts either a single value applied to all asset kinds, or a per-kind\n * record (matching `HeadContent`'s `assetCrossOrigin` shape):\n *\n * ```ts\n * // All assets get the same value\n * crossOrigin: 'anonymous'\n *\n * // Different values per kind\n * crossOrigin: { modulepreload: 'anonymous', stylesheet: 'use-credentials' }\n * ```\n */\nexport type TransformAssetsCrossOriginConfig =\n  | AssetCrossOrigin\n  | Partial<Record<TransformAssetsShorthandCrossOriginKind, AssetCrossOrigin>>\n\n/**\n * Object shorthand for `transformAssets`. Combines a URL prefix with optional\n * per-asset `crossOrigin` without needing a callback:\n *\n * ```ts\n * transformAssets: {\n *   prefix: 'https://cdn.example.com',\n *   crossOrigin: 'anonymous',\n * }\n * ```\n */\nexport interface TransformAssetsObjectShorthand {\n  /** URL prefix prepended to every asset URL. */\n  prefix: string\n  /**\n   * Optional crossOrigin attribute applied to manifest-managed `<link>` assets.\n   *\n   * Accepts a single value or a per-kind record.\n   */\n  crossOrigin?: TransformAssetsCrossOriginConfig\n}\n\nexport type TransformAssets =\n  | string\n  | TransformAssetsFn\n  | TransformAssetsObjectShorthand\n  | TransformAssetsOptions\n\nexport type ResolvedTransformAssetsConfig =\n  | {\n      type: 'transform'\n      transformFn: TransformAssetsFn\n      cache: boolean\n    }\n  | {\n      type: 'createTransform'\n      createTransform: CreateTransformAssetsFn\n      cache: boolean\n    }\n\nlet hasWarnedAboutDeprecatedTransformAssetUrls = false\n\nexport function warnDeprecatedTransformAssetUrls() {\n  if (\n    (process.env.NODE_ENV === 'development' ||\n      process.env.TSS_DEV_SERVER === 'true') &&\n    !hasWarnedAboutDeprecatedTransformAssetUrls\n  ) {\n    hasWarnedAboutDeprecatedTransformAssetUrls = true\n    console.warn(\n      '[TanStack Start] `transformAssetUrls` is deprecated. Use `transformAssets` instead.',\n    )\n  }\n}\n\nfunction normalizeTransformAssetResult(\n  result: TransformAssetResult,\n): Exclude<TransformAssetResult, string> {\n  if (typeof result === 'string') {\n    return { href: result }\n  }\n\n  return result\n}\n\nfunction resolveTransformAssetsCrossOrigin(\n  config: TransformAssetsCrossOriginConfig | undefined,\n  kind: TransformAssetsShorthandCrossOriginKind,\n): AssetCrossOrigin | undefined {\n  if (!config) return undefined\n  if (typeof config === 'string') return config\n\n  return config[kind]\n}\n\nfunction isObjectShorthand(\n  transform: TransformAssetsObjectShorthand | TransformAssetsOptions,\n): transform is TransformAssetsObjectShorthand {\n  return 'prefix' in transform\n}\n\nexport function resolveTransformAssetsConfig(\n  transform: TransformAssets,\n): ResolvedTransformAssetsConfig {\n  if (typeof transform === 'string') {\n    const prefix = transform\n    return {\n      type: 'transform',\n      transformFn: ({ url }) => ({ href: `${prefix}${url}` }),\n      cache: true,\n    }\n  }\n\n  if (typeof transform === 'function') {\n    return {\n      type: 'transform',\n      transformFn: transform,\n      cache: true,\n    }\n  }\n\n  // Object shorthand: { prefix, crossOrigin? }\n  if (isObjectShorthand(transform)) {\n    const { prefix, crossOrigin } = transform\n\n    return {\n      type: 'transform',\n      transformFn: ({ url, kind }) => {\n        const href = `${prefix}${url}`\n\n        if (kind === 'clientEntry') {\n          return { href }\n        }\n\n        const co = resolveTransformAssetsCrossOrigin(crossOrigin, kind)\n        return co ? { href, crossOrigin: co } : { href }\n      },\n      cache: true,\n    }\n  }\n\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 }: TransformAssetsContext) => ({\n          href: `${transform.transform}${url}`,\n        })) as TransformAssetsFn)\n      : transform.transform\n\n  return {\n    type: 'transform',\n    transformFn,\n    cache: transform.cache !== false,\n  }\n}\n\nexport function adaptTransformAssetUrlsToTransformAssets(\n  transformFn: TransformAssetUrlsFn,\n): TransformAssetsFn {\n  return async ({ url, kind }) => ({\n    href: await transformFn({ url, type: kind }),\n  })\n}\n\nexport function adaptTransformAssetUrlsConfigToTransformAssets(\n  transform: TransformAssetUrls,\n): TransformAssets {\n  warnDeprecatedTransformAssetUrls()\n\n  if (typeof transform === 'string') {\n    return transform\n  }\n\n  if (typeof transform === 'function') {\n    return adaptTransformAssetUrlsToTransformAssets(transform)\n  }\n\n  if ('createTransform' in transform && transform.createTransform) {\n    return {\n      createTransform: async (ctx: CreateTransformAssetUrlsContext) =>\n        adaptTransformAssetUrlsToTransformAssets(\n          await transform.createTransform(ctx),\n        ),\n      cache: transform.cache,\n      warmup: transform.warmup,\n    }\n  }\n\n  return {\n    transform:\n      typeof transform.transform === 'string'\n        ? transform.transform\n        : adaptTransformAssetUrlsToTransformAssets(transform.transform),\n    cache: transform.cache,\n    warmup: transform.warmup,\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\nfunction assignManifestAssetLink(\n  link: ManifestAssetLink,\n  next: { href: string; crossOrigin?: AssetCrossOrigin },\n): ManifestAssetLink {\n  if (typeof link === 'string') {\n    return next.crossOrigin ? next : next.href\n  }\n\n  return next.crossOrigin ? next : { href: next.href }\n}\n\nexport async function transformManifestAssets(\n  source: StartManifestWithClientEntry,\n  transformFn: TransformAssetsFn,\n  _opts?: {\n    clone?: boolean\n  },\n): Promise<Manifest> {\n  const manifest = structuredClone(source.manifest)\n\n  for (const route of Object.values(manifest.routes)) {\n    if (route.preloads) {\n      route.preloads = await Promise.all(\n        route.preloads.map(async (link) => {\n          const resolved = resolveManifestAssetLink(link)\n          const result = normalizeTransformAssetResult(\n            await transformFn({\n              url: resolved.href,\n              kind: 'modulepreload',\n            }),\n          )\n\n          return assignManifestAssetLink(link, {\n            href: result.href,\n            crossOrigin: result.crossOrigin,\n          })\n        }),\n      )\n    }\n\n    if (route.assets) {\n      for (const asset of route.assets) {\n        if (asset.tag === 'link' && asset.attrs?.href) {\n          const rel = asset.attrs.rel\n          const relTokens = typeof rel === 'string' ? rel.split(/\\s+/) : []\n\n          if (!relTokens.includes('stylesheet')) {\n            continue\n          }\n\n          const result = normalizeTransformAssetResult(\n            await transformFn({\n              url: asset.attrs.href,\n              kind: 'stylesheet',\n            }),\n          )\n\n          asset.attrs.href = result.href\n          if (result.crossOrigin) {\n            asset.attrs.crossOrigin = result.crossOrigin\n          } else {\n            delete asset.attrs.crossOrigin\n          }\n        }\n      }\n    }\n  }\n\n  const transformedClientEntry = normalizeTransformAssetResult(\n    await transformFn({\n      url: source.clientEntry,\n      kind: '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.href,\n        source.injectedHeadScripts,\n      ),\n    )\n  }\n\n  return manifest\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"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/start-server-core",
-  "version": "1.167.2",
+  "version": "1.167.4",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -66,16 +66,17 @@
     "h3-v2": "npm:h3@2.0.1-rc.16",
     "seroval": "^1.4.2",
     "@tanstack/history": "1.161.6",
-    "@tanstack/router-core": "1.168.2",
-    "@tanstack/start-client-core": "1.167.2",
-    "@tanstack/start-storage-context": "1.166.16"
+    "@tanstack/router-core": "1.168.4",
+    "@tanstack/start-client-core": "1.167.4",
+    "@tanstack/start-storage-context": "1.166.18"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/intent": "^0.0.14",
     "cookie-es": "^2.0.0",
     "fetchdts": "^0.1.6",
-    "vite": "*"
+    "vite": "*",
+    "@types/node": ">=20"
   },
   "bin": {
     "intent": "./bin/intent.js"
@@ -86,12 +87,12 @@
     "test:unit": "vitest",
     "test:eslint": "eslint ./src",
     "test:types": "pnpm run \"/^test:types:ts[0-9]{2}$/\"",
-    "test:types:ts54": "node ../../node_modules/typescript54/lib/tsc.js",
     "test:types:ts55": "node ../../node_modules/typescript55/lib/tsc.js",
     "test:types:ts56": "node ../../node_modules/typescript56/lib/tsc.js",
     "test:types:ts57": "node ../../node_modules/typescript57/lib/tsc.js",
     "test:types:ts58": "node ../../node_modules/typescript58/lib/tsc.js",
-    "test:types:ts59": "tsc",
+    "test:types:ts59": "node ../../node_modules/typescript59/lib/tsc.js",
+    "test:types:ts60": "tsc",
     "test:build": "publint --strict && attw --ignore-rules no-resolution --pack .",
     "build": "vite build"
   }

package/src/createStartHandler.ts

@@ -20,9 +20,10 @@ import { requestHandler } from './request-response'
 import { getStartManifest } from './router-manifest'
 import { handleServerAction } from './server-functions-handler'
 import {
+  adaptTransformAssetUrlsConfigToTransformAssets,
   buildManifestWithClientEntry,
-  resolveTransformConfig,
-  transformManifestUrls,
+  resolveTransformAssetsConfig,
+  transformManifestAssets,
 } from './transformAssetUrls'
 
 import { HEADERS } from './constants'
@@ -47,7 +48,8 @@ import type { HandlerCallback } from '@tanstack/router-core/ssr/server'
 import type {
   StartManifestWithClientEntry,
   TransformAssetUrls,
-  TransformAssetUrlsFn,
+  TransformAssets,
+  TransformAssetsFn,
 } from './transformAssetUrls'
 
 type TODO = any
@@ -59,7 +61,87 @@ type AnyMiddlewareServerFn =
 export interface CreateStartHandlerOptions {
   handler: HandlerCallback<AnyRouter>
   /**
-   * Transform asset URLs at runtime, e.g. to prepend a CDN prefix.
+   * Transform asset URLs and attributes 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,
+   *   transformAssets: 'https://cdn.example.com',
+   * })
+   * ```
+   *
+   * **Object shorthand** — a URL prefix with optional `crossOrigin`:
+   * ```ts
+   * createStartHandler({
+   *   handler: defaultStreamHandler,
+   *   transformAssets: {
+   *     prefix: 'https://cdn.example.com',
+   *     crossOrigin: 'anonymous',
+   *   },
+   * })
+   * ```
+   *
+   * `crossOrigin` accepts a single value or a per-kind record:
+   * ```ts
+   * transformAssets: {
+   *   prefix: 'https://cdn.example.com',
+   *   crossOrigin: {
+   *     modulepreload: 'anonymous',
+   *     stylesheet: 'use-credentials',
+   *   },
+   * }
+   * ```
+   *
+   * **Callback** — receives `{ kind, url }` and returns either a string URL or
+   * `{ href, crossOrigin? }` (cached by default — runs once on first request):
+   * ```ts
+   * createStartHandler({
+   *   handler: defaultStreamHandler,
+   *   transformAssets: ({ kind, url }) => {
+   *     const href = `https://cdn.example.com${url}`
+   *
+   *     if (kind === 'modulepreload') {
+   *       return { href, crossOrigin: 'anonymous' }
+   *     }
+   *
+   *     return { href }
+   *   },
+   * })
+   * ```
+   *
+   * **Object** — for explicit cache control:
+   * ```ts
+   * createStartHandler({
+   *   handler: defaultStreamHandler,
+   *   transformAssets: {
+   *     transform: ({ url }) => {
+   *       const region = getRequest().headers.get('x-region') || 'us'
+   *       return { href: `https://cdn-${region}.example.com${url}` }
+   *     },
+   *     cache: false,
+   *   },
+   * })
+   * ```
+   *
+   * `kind` is one of `'modulepreload' | 'stylesheet' | 'clientEntry'`.
+   * `crossOrigin` applies to manifest-managed `<link>` assets.
+   *
+   * 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.
+   */
+  transformAssets?: TransformAssets
+  /**
+   * @deprecated Use `transformAssets` instead.
    *
    * **String** — a URL prefix prepended to every asset URL (cached by default):
    * ```ts
@@ -181,14 +263,14 @@ function getBaseManifest(
  */
 async function resolveManifest(
   matchedRoutes: ReadonlyArray<AnyRoute> | undefined,
-  transformFn: TransformAssetUrlsFn | undefined,
+  transformFn: TransformAssetsFn | undefined,
   cache: boolean,
 ): Promise<Manifest> {
   const base = await getBaseManifest(matchedRoutes)
 
   const computeFinalManifest = async () => {
     return transformFn
-      ? await transformManifestUrls(base, transformFn, { clone: !cache })
+      ? await transformManifestAssets(base, transformFn, { clone: !cache })
       : buildManifestWithClientEntry(base)
   }
 
@@ -332,7 +414,7 @@ function handlerToMiddleware(
  * ```ts
  * export default createStartHandler({
  *   handler: defaultStreamHandler,
- *   transformAssetUrls: 'https://cdn.example.com',
+ *   transformAssets: 'https://cdn.example.com',
  * })
  * ```
  *
@@ -340,10 +422,10 @@ function handlerToMiddleware(
  * ```ts
  * export default createStartHandler({
  *   handler: defaultStreamHandler,
- *   transformAssetUrls: {
+ *   transformAssets: {
  *     transform: ({ url }) => {
  *       const cdnBase = getRequest().headers.get('x-cdn-base') || ''
- *       return `${cdnBase}${url}`
+ *       return { href: `${cdnBase}${url}` }
  *     },
  *     cache: false,
  *   },
@@ -356,40 +438,65 @@ export function createStartHandler<TRegister = Register>(
   // Normalize the overloaded argument
   const cb: HandlerCallback<AnyRouter> =
     typeof cbOrOptions === 'function' ? cbOrOptions : cbOrOptions.handler
+  const transformAssetsOption: TransformAssets | undefined =
+    typeof cbOrOptions === 'function' ? undefined : cbOrOptions.transformAssets
   const transformAssetUrlsOption: TransformAssetUrls | undefined =
     typeof cbOrOptions === 'function'
       ? undefined
       : cbOrOptions.transformAssetUrls
 
+  const transformOption =
+    transformAssetsOption !== undefined
+      ? resolveTransformAssetsConfig(transformAssetsOption)
+      : transformAssetUrlsOption !== undefined
+        ? resolveTransformAssetsConfig(
+            adaptTransformAssetUrlsConfigToTransformAssets(
+              transformAssetUrlsOption,
+            ),
+          )
+        : undefined
+
   const warmupTransformManifest =
-    !!transformAssetUrlsOption &&
-    typeof transformAssetUrlsOption === 'object' &&
-    transformAssetUrlsOption.warmup === true
+    (!!transformAssetsOption &&
+      typeof transformAssetsOption === 'object' &&
+      'warmup' in transformAssetsOption &&
+      transformAssetsOption.warmup === true) ||
+    (!!transformAssetUrlsOption &&
+      typeof transformAssetUrlsOption === 'object' &&
+      transformAssetUrlsOption.warmup === true)
 
   // Pre-resolve the transform function and cache flag
-  const resolvedTransformConfig = transformAssetUrlsOption
-    ? resolveTransformConfig(transformAssetUrlsOption)
-    : undefined
+  const resolvedTransformConfig = transformOption
   const cache = resolvedTransformConfig ? resolvedTransformConfig.cache : true
+  const shouldCacheCreateTransform =
+    cache && process.env.TSS_DEV_SERVER !== 'true'
 
-  // Memoize a single createTransform() result when caching is enabled.
-  let cachedCreateTransformPromise: Promise<TransformAssetUrlsFn> | undefined
+  // Memoize a single createTransform() result when caching is enabled outside
+  // of the dev server.
+  let cachedCreateTransformPromise: Promise<TransformAssetsFn> | undefined
 
   const getTransformFn = async (
     opts: { warmup: true } | { warmup: false; request: Request },
-  ): Promise<TransformAssetUrlsFn | undefined> => {
+  ): Promise<TransformAssetsFn | undefined> => {
     if (!resolvedTransformConfig) return undefined
+
     if (resolvedTransformConfig.type === 'createTransform') {
-      if (cache) {
+      if (shouldCacheCreateTransform) {
         if (!cachedCreateTransformPromise) {
           cachedCreateTransformPromise = Promise.resolve(
             resolvedTransformConfig.createTransform(opts),
-          )
+          ).catch((error) => {
+            cachedCreateTransformPromise = undefined
+            throw error
+          })
         }
+
         return cachedCreateTransformPromise
       }
+
       return resolvedTransformConfig.createTransform(opts)
     }
+
     return resolvedTransformConfig.transformFn
   }
 
@@ -408,7 +515,7 @@ export function createStartHandler<TRegister = Register>(
       const base = await getBaseManifest(undefined)
       const transformFn = await getTransformFn({ warmup: true })
       return transformFn
-        ? await transformManifestUrls(base, transformFn, { clone: false })
+        ? await transformManifestAssets(base, transformFn, { clone: false })
         : buildManifestWithClientEntry(base)
     })()
     cachedFinalManifestPromise = warmupPromise

package/src/index.tsx

@@ -2,11 +2,19 @@ export { createStartHandler } from './createStartHandler'
 export type { CreateStartHandlerOptions } from './createStartHandler'
 
 export type {
+  TransformAssets,
+  TransformAssetsFn,
+  TransformAssetsContext,
+  TransformAssetsOptions,
+  TransformAssetsObjectShorthand,
+  TransformAssetsCrossOriginConfig,
+  TransformAssetResult,
   TransformAssetUrls,
   TransformAssetUrlsFn,
   TransformAssetUrlsContext,
   TransformAssetUrlsOptions,
   AssetUrlType,
+  TransformAssetKind,
 } from './transformAssetUrls'
 
 export {

package/src/router-manifest.ts

@@ -1,5 +1,9 @@
 import { buildDevStylesUrl, rootRouteId } from '@tanstack/router-core'
-import type { AnyRoute, RouterManagedTag } from '@tanstack/router-core'
+import type {
+  AnyRoute,
+  ManifestAssetLink,
+  RouterManagedTag,
+} from '@tanstack/router-core'
 import type { StartManifestWithClientEntry } from './transformAssetUrls'
 
 // Pre-computed constant for dev styles URL basepath.
@@ -61,7 +65,7 @@ export async function getStartManifest(
     routes: Object.fromEntries(
       Object.entries(startManifest.routes).flatMap(([k, v]) => {
         const result = {} as {
-          preloads?: Array<string>
+          preloads?: Array<ManifestAssetLink>
           assets?: Array<RouterManagedTag>
         }
         let hasData = false
@@ -82,7 +86,7 @@ export async function getStartManifest(
   }
 
   return {
-    manifest,
+    manifest: manifest as StartManifestWithClientEntry['manifest'],
     clientEntry: startManifest.clientEntry,
     injectedHeadScripts,
   }