Skip to content
Source
Sign inSign up
TanStack/router
Open History to see the last commit

transformAssetUrls.ts

473 lines11.5 KB

1import {
2 resolveManifestAssetLink,
3 resolveManifestCssLink,
4} from '@tanstack/router-core'
5​
6import type {
7 AssetCrossOrigin,
8 Awaitable,
9 ManifestAssetLink,
10 ManifestCssLink,
11 ServerManifest,
12} from '@tanstack/router-core'
13​
14export type { AssetCrossOrigin }
15​
16export type TransformAssetsContext =
17 | {
18 url: string
19 kind: 'script'
20 }
21 | {
22 url: string
23 kind: 'stylesheet'
24 }
25 | {
26 url: string
27 kind: 'css-url'
28 stylesheetHref: string
29 }
30​
31export type TransformAssetKind = TransformAssetsContext['kind']
32​
33type TransformAssetsShorthandCrossOriginKind = Exclude<
34 TransformAssetKind,
35 'css-url'
37​
38export type TransformAssetResult =
39 | string
40 | {
41 href: string
42 crossOrigin?: AssetCrossOrigin
43 }
44​
45export type TransformAssetsFn = (
46 context: TransformAssetsContext,
47) => Awaitable<TransformAssetResult>
48​
49export type CreateTransformAssetsContext =
50 | {
51 /** True when the server is computing the cached manifest during startup warmup. */
52 warmup: true
53 }
54 | {
55 /**
56 * The current Request.
57 *
58 * Only available during request handling (i.e. when `warmup: false`).
59 */
60 request: Request
61 /** False when transforming URLs as part of request handling. */
62 warmup: false
63 }
64​
65export type CreateTransformAssetsFn = (
66 ctx: CreateTransformAssetsContext,
67) => Awaitable<TransformAssetsFn>
68​
69type TransformAssetsOptionsBase = {
70 /**
71 * Whether to cache the transformed manifest after the first request.
72 *
73 * When `true` (default), the transform runs once on the first request and
74 * the resulting manifest is reused for all subsequent requests in production.
75 *
76 * Set to `false` for per-request transforms (e.g. geo-routing to different
77 * CDNs based on request headers).
78 *
79 * @default true
80 */
81 cache?: boolean
82​
83 /**
84 * When `true`, warms up the cached transformed manifest in the background when
85 * the server starts (production only).
86 *
87 * This can reduce latency for the first request when `cache` is `true`.
88 * Has no effect when `cache: false` (per-request transforms) or in dev mode.
89 *
90 * @default false
91 */
92 warmup?: boolean
94​
95export type TransformAssetsOptions =
96 | (TransformAssetsOptionsBase & {
97 transform: string | TransformAssetsFn
98 createTransform?: never
99 })
100 | (TransformAssetsOptionsBase & {
101 createTransform: CreateTransformAssetsFn
102 transform?: never
103 })
104​
105/**
106 * Per-kind crossOrigin configuration for the object shorthand.
107 *
108 * Accepts either a single value applied to all asset kinds, or a per-kind
109 * record (matching `HeadContent`'s `assetCrossOrigin` shape):
110 *
111 * ```ts
112 * // All assets get the same value
113 * crossOrigin: 'anonymous'
114 *
115 * // Different values per kind
116 * crossOrigin: { script: 'anonymous', stylesheet: 'use-credentials' }
117 * ```
118 */
119export type TransformAssetsCrossOriginConfig =
120 | AssetCrossOrigin
121 | Partial<Record<TransformAssetsShorthandCrossOriginKind, AssetCrossOrigin>>
122​
123/**
124 * Object shorthand for `transformAssets`. Combines a URL prefix with optional
125 * per-asset `crossOrigin` without needing a callback:
126 *
127 * ```ts
128 * transformAssets: {
129 * prefix: 'https://cdn.example.com',
130 * crossOrigin: 'anonymous',
131 * }
132 * ```
133 */
134export interface TransformAssetsObjectShorthand {
135 /** URL prefix prepended to every asset URL. */
136 prefix: string
137 /**
138 * Optional crossOrigin attribute applied to transformed script and stylesheet assets.
139 *
140 * Accepts a single value or a per-kind record.
141 */
142 crossOrigin?: TransformAssetsCrossOriginConfig
144​
145export type TransformAssets =
146 | string
147 | TransformAssetsFn
148 | TransformAssetsObjectShorthand
149 | TransformAssetsOptions
150​
151export type ResolvedTransformAssetsConfig =
152 | {
153 type: 'transform'
154 transformFn: TransformAssetsFn
155 cache: boolean
156 }
157 | {
158 type: 'createTransform'
159 createTransform: CreateTransformAssetsFn
160 cache: boolean
161 }
162​
163function normalizeTransformAssetResult(
164 result: TransformAssetResult,
165): Exclude<TransformAssetResult, string> {
166 if (typeof result === 'string') {
167 return { href: result }
168 }
169​
170 return result
172​
173function escapeCssString(value: string) {
174 return value
175 .replace(/\\/g, '\\\\')
176 .replace(/"/g, '\\"')
177 .replace(/\n/g, '\\a ')
178 .replace(/\r/g, '\\d ')
179 .replace(/\f/g, '\\c ')
181​
182async function transformInlineCssTemplate(options: {
183 stylesheetHref: string
184 template: { strings: Array<string>; urls: Array<string> }
185 transformFn: TransformAssetsFn
186}) {
187 const { strings, urls } = options.template
188​
189 if (strings.length !== urls.length + 1) {
190 throw new Error(
191 `TanStack Start inlineCss template for ${options.stylesheetHref} is invalid`,
192 )
193 }
194​
195 let css = strings[0]!
196​
197 for (let index = 0; index < urls.length; index++) {
198 const transformed = normalizeTransformAssetResult(
199 await options.transformFn({
200 kind: 'css-url',
201 url: urls[index]!,
202 stylesheetHref: options.stylesheetHref,
203 }),
204 )
205​
206 css += escapeCssString(transformed.href) + strings[index + 1]!
207 }
208​
209 return css
211​
212async function transformInlineCssStyles(
213 inlineCss: NonNullable<ServerManifest['inlineCss']>,
214 transformFn: TransformAssetsFn,
215) {
216 const transformedStyles: Record<string, string> = {}
217​
218 const transformedEntries = await Promise.all(
219 Object.entries(inlineCss.styles).map(async ([stylesheetHref, css]) => {
220 const template = inlineCss.templates?.[stylesheetHref]
221 return [
222 stylesheetHref,
223 template
224 ? await transformInlineCssTemplate({
225 stylesheetHref,
226 template,
227 transformFn,
228 })
229 : css,
230 ] as const
231 }),
232 )
233​
234 for (const [stylesheetHref, css] of transformedEntries) {
235 transformedStyles[stylesheetHref] = css
236 }
237​
238 return {
239 styles: transformedStyles,
240 ...(inlineCss.templates ? { templates: inlineCss.templates } : {}),
241 }
243​
244function resolveTransformAssetsCrossOrigin(
245 config: TransformAssetsCrossOriginConfig | undefined,
246 kind: TransformAssetsShorthandCrossOriginKind,
247): AssetCrossOrigin | undefined {
248 if (!config) return undefined
249 if (typeof config === 'string') return config
250​
251 return config[kind]
253​
254function isObjectShorthand(
255 transform: TransformAssetsObjectShorthand | TransformAssetsOptions,
256): transform is TransformAssetsObjectShorthand {
257 return 'prefix' in transform
259​
260export function resolveTransformAssetsConfig(
261 transform: TransformAssets,
262): ResolvedTransformAssetsConfig {
263 if (typeof transform === 'string') {
264 const prefix = transform
265 return {
266 type: 'transform',
267 transformFn: ({ url }) => ({ href: `${prefix}${url}` }),
268 cache: true,
269 }
270 }
271​
272 if (typeof transform === 'function') {
273 return {
274 type: 'transform',
275 transformFn: transform,
276 cache: true,
277 }
278 }
279​
280 // Object shorthand: { prefix, crossOrigin? }
281 if (isObjectShorthand(transform)) {
282 const { prefix, crossOrigin } = transform
283​
284 return {
285 type: 'transform',
286 transformFn: ({ url, kind }) => {
287 const href = `${prefix}${url}`
288​
289 if (kind === 'css-url') {
290 return { href }
291 }
292​
293 const co = resolveTransformAssetsCrossOrigin(crossOrigin, kind)
294 return co ? { href, crossOrigin: co } : { href }
295 },
296 cache: true,
297 }
298 }
299​
300 if ('createTransform' in transform && transform.createTransform) {
301 return {
302 type: 'createTransform',
303 createTransform: transform.createTransform,
304 cache: transform.cache !== false,
305 }
306 }
307​
308 const transformFn =
309 typeof transform.transform === 'string'
310 ? ((({ url }: TransformAssetsContext) => ({
311 href: `${transform.transform}${url}`,
312 })) as TransformAssetsFn)
313 : transform.transform
314​
315 return {
316 type: 'transform',
317 transformFn,
318 cache: transform.cache !== false,
319 }
321​
322type AssignableManifestLink = ManifestAssetLink | ManifestCssLink
323​
324function assignManifestLink(
325 link: ManifestAssetLink,
326 next: { href: string; crossOrigin?: AssetCrossOrigin },
327): ManifestAssetLink
328function assignManifestLink(
329 link: ManifestCssLink,
330 next: { href: string; crossOrigin?: AssetCrossOrigin },
331): ManifestCssLink
332function assignManifestLink(
333 link: AssignableManifestLink,
334 next: { href: string; crossOrigin?: AssetCrossOrigin },
335): AssignableManifestLink {
336 if (typeof link === 'string') {
337 return next.crossOrigin ? next : next.href
338 }
339​
340 const nextLink: Exclude<ManifestCssLink, string> = {
341 ...link,
342 href: next.href,
343 }
344​
345 if (next.crossOrigin) {
346 nextLink.crossOrigin = next.crossOrigin
347 } else {
348 delete nextLink.crossOrigin
349 }
350​
351 return nextLink
353​
354export async function transformManifestAssets(
355 source: ServerManifest,
356 transformFn: TransformAssetsFn,
357 _opts?: {
358 clone?: boolean
359 inlineCss?: boolean
360 },
361): Promise<ServerManifest> {
362 const manifest = structuredClone(source)
363 const inlineCssEnabled = _opts?.inlineCss !== false
364 const scriptTransforms = new Map<
365 string,
366 Promise<Exclude<TransformAssetResult, string>>
367 >()
368 const transformScript = (url: string) => {
369 const cached = scriptTransforms.get(url)
370 if (cached) {
371 return cached
372 }
373​
374 const transformed = Promise.resolve(
375 transformFn({
376 url,
377 kind: 'script',
378 }),
379 ).then(normalizeTransformAssetResult)
380 scriptTransforms.set(url, transformed)
381 return transformed
382 }
383​
384 if (!inlineCssEnabled) {
385 delete manifest.inlineCss
386 } else if (manifest.inlineCss) {
387 manifest.inlineCss = await transformInlineCssStyles(
388 manifest.inlineCss,
389 transformFn,
390 )
391 }
392​
393 for (const route of Object.values(manifest.routes)) {
394 if (route.preloads?.length) {
395 route.preloads = await Promise.all(
396 route.preloads.map(async (link) => {
397 const resolved = resolveManifestAssetLink(link)
398 const result = await transformScript(resolved.href)
399​
400 return assignManifestLink(link, {
401 href: result.href,
402 crossOrigin: result.crossOrigin,
403 })
404 }),
405 )
406 }
407​
408 if (route.css?.length && !manifest.inlineCss) {
409 route.css = await Promise.all(
410 route.css.map(async (link) => {
411 const resolved = resolveManifestCssLink(link)
412 const result = normalizeTransformAssetResult(
413 await transformFn({
414 url: resolved.href,
415 kind: 'stylesheet',
416 }),
417 )
418​
419 return assignManifestLink(link, {
420 href: result.href,
421 crossOrigin: result.crossOrigin,
422 })
423 }),
424 )
425 }
426​
427 if (route.scripts?.length) {
428 for (const script of route.scripts) {
429 const src = script.attrs?.src
430 if (typeof src !== 'string') {
431 continue
432 }
433​
434 const result = await transformScript(src)
435​
436 script.attrs = {
437 ...script.attrs,
438 src: result.href,
439 }
440 if (result.crossOrigin) {
441 script.attrs.crossOrigin = result.crossOrigin
442 } else {
443 delete script.attrs.crossOrigin
444 }
445 }
446 }
447 }
448​
449 return manifest
451​
452/**
453 * Builds a final ServerManifest without URL transforms. Used when no
454 * transformAssets option is provided.
455 *
456 * Returns a new manifest object so the cached base manifest is never mutated.
457 */
458export function buildManifest(
459 source: ServerManifest,
460 opts?: { inlineCss?: boolean },
461): ServerManifest {
462 const manifest: ServerManifest = {
463 ...(source.scriptFormat ? { scriptFormat: source.scriptFormat } : {}),
464 ...(opts?.inlineCss !== false && source.inlineCss
465 ? { inlineCss: structuredClone(source.inlineCss) }
466 : {}),
467 routes: {
468 ...source.routes,
469 },
470 }
471​
472 return manifest