Open History to see the last commit
1import {
2 getScriptPreloadAttrs,
3 getStylesheetHref,
4 resolveManifestCssLink,
5} from '@tanstack/router-core'
6import type {
7 AnyRoute,
8 AnyRouteMatch,
9 AssetCrossOrigin,
10 RouterManagedTag,
11 ServerManifest,
12} from '@tanstack/router-core'
13β
14export type EarlyHint = {
15 href: string
16 rel: 'preload' | 'modulepreload' | 'preconnect' | 'dns-prefetch'
17 as?: 'fetch' | 'font' | 'image' | 'script' | 'style' | 'track'
18 crossOrigin?: AssetCrossOrigin | ''
19 type?: string
20 integrity?: string
21 referrerPolicy?: string
22 fetchPriority?: string
23}
24β
25export type EarlyHintsPhase = 'static' | 'dynamic'
26β
27export type EarlyHintsEvent = {
28 phase: EarlyHintsPhase
29 hints: ReadonlyArray<EarlyHint>
30 links: Array<string>
31 allHints: ReadonlyArray<EarlyHint>
32 allLinks: Array<string>
33}
34β
35export type OnEarlyHints = (event: EarlyHintsEvent) => void | Promise<void>
36β
37export type ResponseLinkHeaderEntry = {
38 phase: EarlyHintsPhase
39 hint: EarlyHint
40 link: string
41}
42β
43export type ResponseLinkHeaderFilter = (
44 entry: ResponseLinkHeaderEntry,
45) => boolean
46β
47export type ResponseLinkHeaderOptions = {
48 filter?: ResponseLinkHeaderFilter
49}
50β
51export interface EarlyHintsCollector {
52 collectStatic: (opts: {
53 manifest: ServerManifest
54 matchedRoutes?: ReadonlyArray<AnyRoute>
55 }) => void
56 collectDynamic: (matches: ReadonlyArray<AnyRouteMatch>) => void
57 appendResponseHeaders: (headers: Headers) => void
58}
59β
60const LINK_PARAM_TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
61const PRELOAD_AS_VALUES = new Set<EarlyHint['as']>([
62 'fetch',
63 'font',
64 'image',
65 'script',
66 'style',
67 'track',
68])
69β
70function buildLinkParam(name: string, value: string | undefined): string {
71 if (value === undefined) return name
72 if (LINK_PARAM_TOKEN_RE.test(value)) return `${name}=${value}`
73 return `${name}=${JSON.stringify(value)}`
74}
75β
76export function serializeEarlyHint(hint: EarlyHint): string {
77 const parts = [`<${hint.href}>`, buildLinkParam('rel', hint.rel)]
78 if (hint.as) parts.push(buildLinkParam('as', hint.as))
79 if (hint.crossOrigin !== undefined) {
80 parts.push(buildLinkParam('crossorigin', hint.crossOrigin || undefined))
81 }
82 if (hint.type) parts.push(buildLinkParam('type', hint.type))
83 if (hint.integrity) parts.push(buildLinkParam('integrity', hint.integrity))
84 if (hint.referrerPolicy) {
85 parts.push(buildLinkParam('referrerpolicy', hint.referrerPolicy))
86 }
87 if (hint.fetchPriority) {
88 parts.push(buildLinkParam('fetchpriority', hint.fetchPriority))
89 }
90 return parts.join('; ')
91}
92β
93function getStringAttr(
94 attrs: Record<string, any> | undefined,
95 name: string,
96 fallbackName?: string,
97): string | undefined {
98 const value =
99 attrs?.[name] ?? (fallbackName ? attrs?.[fallbackName] : undefined)
100 return typeof value === 'string' ? value : undefined
101}
102β
103function getPreloadAs(
104 attrs: Record<string, any> | undefined,
105): EarlyHint['as'] | undefined {
106 const as = getStringAttr(attrs, 'as')
107 return as && PRELOAD_AS_VALUES.has(as as EarlyHint['as'])
108 ? (as as EarlyHint['as'])
109 : undefined
110}
111β
112function addEarlyHintFetchAttrs(
113 hint: EarlyHint,
114 attrs: Record<string, any> | undefined,
115) {
116 const crossOrigin = getStringAttr(attrs, 'crossOrigin', 'crossorigin') as
117 | EarlyHint['crossOrigin']
118 | undefined
119 const type = getStringAttr(attrs, 'type')
120 const integrity = getStringAttr(attrs, 'integrity')
121 const referrerPolicy = getStringAttr(
122 attrs,
123 'referrerPolicy',
124 'referrerpolicy',
125 )
126 const fetchPriority = getStringAttr(attrs, 'fetchPriority', 'fetchpriority')
127β
128 if (crossOrigin !== undefined) hint.crossOrigin = crossOrigin
129 if (type) hint.type = type
130 if (integrity) hint.integrity = integrity
131 if (referrerPolicy) hint.referrerPolicy = referrerPolicy
132 if (fetchPriority) hint.fetchPriority = fetchPriority
133}
134β
135function linkAttrsToEarlyHint(
136 attrs: Record<string, any> | undefined,
137): EarlyHint | undefined {
138 const href = getStringAttr(attrs, 'href')
139 const rel = getStringAttr(attrs, 'rel')
140 if (!href || !rel) return undefined
141β
142 const relTokens = rel.split(/\s+/)
143 let hintRel: EarlyHint['rel'] | undefined
144 let hintAs: EarlyHint['as'] | undefined
145β
146 if (relTokens.includes('modulepreload')) {
147 hintRel = 'modulepreload'
148 hintAs = 'script'
149 } else if (relTokens.includes('stylesheet')) {
150 hintRel = 'preload'
151 hintAs = 'style'
152 } else if (relTokens.includes('preload')) {
153 hintAs = getPreloadAs(attrs)
154 if (!hintAs) return undefined
155 hintRel = 'preload'
156 } else if (relTokens.includes('preconnect')) {
157 hintRel = 'preconnect'
158 hintAs = undefined
159 } else if (relTokens.includes('dns-prefetch')) {
160 hintRel = 'dns-prefetch'
161 hintAs = undefined
162 }
163β
164 if (!hintRel) return undefined
165β
166 const hint: EarlyHint = {
167 href,
168 rel: hintRel,
169 }
170β
171 if (hintAs) hint.as = hintAs
172 addEarlyHintFetchAttrs(hint, attrs)
173β
174 return hint
175}
176β
177export function collectStaticHintsFromManifest(
178 manifest: ServerManifest,
179 matchedRoutes: ReadonlyArray<AnyRoute>,
180): Array<EarlyHint> {
181 const hints: Array<EarlyHint> = []
182β
183 for (const route of matchedRoutes) {
184 const routeManifest = manifest.routes[route.id]
185 if (!routeManifest) continue
186β
187 for (const link of routeManifest.preloads ?? []) {
188 const attrs = getScriptPreloadAttrs(manifest, link)
189 const hint: EarlyHint = {
190 href: attrs.href,
191 rel: attrs.rel,
192 as: 'script',
193 }
194 addEarlyHintFetchAttrs(hint, attrs)
195 hints.push(hint)
196 }
197β
198 for (const link of routeManifest.css ?? []) {
199 const stylesheetHref = getStylesheetHref(link)
200 if (manifest.inlineCss?.styles[stylesheetHref] !== undefined) {
201 continue
202 }
203 const resolvedLink = resolveManifestCssLink(link)
204β
205 const hint: EarlyHint = {
206 href: stylesheetHref,
207 rel: 'preload',
208 as: 'style',
209 }
210 if (resolvedLink.crossOrigin !== undefined) {
211 hint.crossOrigin = resolvedLink.crossOrigin
212 }
213 hints.push(hint)
214 }
215 }
216β
217 return hints
218}
219β
220export function collectDynamicHintsFromMatches(
221 matches: ReadonlyArray<AnyRouteMatch>,
222): Array<EarlyHint> {
223 const hints: Array<EarlyHint> = []
224β
225 for (const match of matches) {
226 const links = match.links
227 if (!Array.isArray(links)) continue
228β
229 for (const link of links as Array<RouterManagedTag['attrs']>) {
230 const hint = linkAttrsToEarlyHint(link)
231 if (hint) hints.push(hint)
232 }
233 }
234β
235 return hints
236}
237β
238export function createEarlyHintsEvent(opts: {
239 phase: EarlyHintsPhase
240 hints: ReadonlyArray<EarlyHint>
241 sentLinks: Set<string>
242 sentHints: Array<EarlyHint>
243}): EarlyHintsEvent | undefined {
244 const nextHints: Array<EarlyHint> = []
245 const nextLinks: Array<string> = []
246β
247 for (const hint of opts.hints) {
248 const link = serializeEarlyHint(hint)
249 if (opts.sentLinks.has(link)) continue
250 opts.sentLinks.add(link)
251 opts.sentHints.push(hint)
252 nextHints.push(hint)
253 nextLinks.push(link)
254 }
255β
256 if (!nextHints.length && opts.phase !== 'dynamic') return undefined
257β
258 return {
259 phase: opts.phase,
260 hints: nextHints,
261 links: nextLinks,
262 allHints: opts.sentHints.slice(),
263 allLinks: Array.from(opts.sentLinks),
264 }
265}
266β
267export function createResponseLinkHeaderEntries(opts: {
268 phase: EarlyHintsPhase
269 hints: ReadonlyArray<EarlyHint>
270 sentLinks: Set<string>
271 entries: Array<ResponseLinkHeaderEntry>
272}) {
273 for (const hint of opts.hints) {
274 const link = serializeEarlyHint(hint)
275 if (opts.sentLinks.has(link)) continue
276β
277 opts.sentLinks.add(link)
278 opts.entries.push({ phase: opts.phase, hint, link })
279 }
280}
281β
282export function getResponseLinkHeaderEntries(opts: {
283 entries: ReadonlyArray<ResponseLinkHeaderEntry>
284 filter?: ResponseLinkHeaderFilter
285}): Array<string> {
286 if (!opts.filter) {
287 return opts.entries.map((entry) => entry.link)
288 }
289β
290 try {
291 const links: Array<string> = []
292β
293 for (const entry of opts.entries) {
294 if (opts.filter(entry)) {
295 links.push(entry.link)
296 }
297 }
298β
299 return links
300 } catch (err) {
301 console.error('Error filtering response Link headers:', err)
302 return []
303 }
304}
305β
306function notifyEarlyHints(
307 phase: EarlyHintsPhase,
308 event: EarlyHintsEvent,
309 onEarlyHints: OnEarlyHints,
310) {
311 try {
312 const result = onEarlyHints(event)
313 if (result) {
314 void Promise.resolve(result).catch((err) => {
315 console.error(`Error sending ${phase} early hints:`, err)
316 })
317 }
318 } catch (err) {
319 console.error(`Error sending ${phase} early hints:`, err)
320 }
321}
322β
323function getResponseLinkHeaderFilter(
324 responseLinkHeader: boolean | ResponseLinkHeaderOptions | undefined,
325): ResponseLinkHeaderFilter | undefined {
326 if (typeof responseLinkHeader !== 'object') {
327 return undefined
328 }
329β
330 return responseLinkHeader.filter
331}
332β
333function appendResponseLinkHeaders(opts: {
334 responseHeaders: Headers
335 entries: ReadonlyArray<ResponseLinkHeaderEntry>
336 filter?: ResponseLinkHeaderFilter
337}) {
338 for (const link of getResponseLinkHeaderEntries(opts)) {
339 opts.responseHeaders.append('Link', link)
340 }
341}
342β
343function collectResponseLinkHeaderEntries(opts: {
344 phase: EarlyHintsPhase
345 event: EarlyHintsEvent
346 entries: Array<ResponseLinkHeaderEntry>
347}) {
348 for (let index = 0; index < opts.event.hints.length; index++) {
349 opts.entries.push({
350 phase: opts.phase,
351 hint: opts.event.hints[index]!,
352 link: opts.event.links[index]!,
353 })
354 }
355}
356β
357function collectEarlyHintsPhase(opts: {
358 phase: EarlyHintsPhase
359 hints: ReadonlyArray<EarlyHint>
360 sentLinks: Set<string>
361 sentHints?: Array<EarlyHint>
362 onEarlyHints?: OnEarlyHints
363 responseLinkHeaderEntries?: Array<ResponseLinkHeaderEntry>
364}) {
365 const event = opts.onEarlyHints
366 ? createEarlyHintsEvent({
367 phase: opts.phase,
368 hints: opts.hints,
369 sentLinks: opts.sentLinks,
370 sentHints: opts.sentHints!,
371 })
372 : undefined
373β
374 if (event) {
375 notifyEarlyHints(opts.phase, event, opts.onEarlyHints!)
376 }
377β
378 if (!opts.responseLinkHeaderEntries) return
379β
380 if (event) {
381 collectResponseLinkHeaderEntries({
382 phase: opts.phase,
383 event,
384 entries: opts.responseLinkHeaderEntries,
385 })
386 return
387 }
388β
389 createResponseLinkHeaderEntries({
390 phase: opts.phase,
391 hints: opts.hints,
392 sentLinks: opts.sentLinks,
393 entries: opts.responseLinkHeaderEntries,
394 })
395}
396β
397export function createEarlyHintsCollector(
398 opts:
399 | {
400 onEarlyHints?: OnEarlyHints
401 responseLinkHeader?: boolean | ResponseLinkHeaderOptions
402 }
403 | undefined,
404): EarlyHintsCollector | undefined {
405 if (
406 process.env.TSS_DEV_SERVER === 'true' ||
407 (!opts?.onEarlyHints && !opts?.responseLinkHeader)
408 ) {
409 return undefined
410 }
411β
412 const sentLinks = new Set<string>()
413 const sentHints = opts.onEarlyHints ? new Array<EarlyHint>() : undefined
414 const responseLinkHeaderEntries = opts.responseLinkHeader
415 ? new Array<ResponseLinkHeaderEntry>()
416 : undefined
417 const responseLinkHeaderFilter = getResponseLinkHeaderFilter(
418 opts.responseLinkHeader,
419 )
420β
421 return {
422 collectStatic: ({ manifest, matchedRoutes }) => {
423 if (!matchedRoutes?.length) return
424β
425 collectEarlyHintsPhase({
426 phase: 'static',
427 hints: collectStaticHintsFromManifest(manifest, matchedRoutes),
428 sentLinks,
429 sentHints,
430 onEarlyHints: opts.onEarlyHints,
431 responseLinkHeaderEntries,
432 })
433 },
434 collectDynamic: (matches) => {
435 collectEarlyHintsPhase({
436 phase: 'dynamic',
437 hints: collectDynamicHintsFromMatches(matches),
438 sentLinks,
439 sentHints,
440 onEarlyHints: opts.onEarlyHints,
441 responseLinkHeaderEntries,
442 })
443 },
444 appendResponseHeaders: (headers) => {
445 if (!responseLinkHeaderEntries?.length) return
446β
447 appendResponseLinkHeaders({
448 responseHeaders: headers,
449 entries: responseLinkHeaderEntries,
450 filter: responseLinkHeaderFilter,
451 })
452 },
453 }
454}