@tanstack/start-server-core 1.168.0 → 1.168.1

package/src/early-hints.ts

@@ -47,6 +47,15 @@ export type ResponseLinkHeaderOptions = {
   filter?: ResponseLinkHeaderFilter
 }
 
+export interface EarlyHintsCollector {
+  collectStatic: (opts: {
+    manifest: Manifest
+    matchedRoutes?: ReadonlyArray<AnyRoute>
+  }) => void
+  collectDynamic: (matches: ReadonlyArray<AnyRouteMatch>) => void
+  appendResponseHeaders: (headers: Headers) => void
+}
+
 const LINK_PARAM_TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/
 const PRELOAD_AS_VALUES = new Set<EarlyHint['as']>([
   'fetch',
@@ -293,3 +302,153 @@ export function getResponseLinkHeaderEntries(opts: {
     return []
   }
 }
+
+function notifyEarlyHints(
+  phase: EarlyHintsPhase,
+  event: EarlyHintsEvent,
+  onEarlyHints: OnEarlyHints,
+) {
+  try {
+    const result = onEarlyHints(event)
+    if (result) {
+      void Promise.resolve(result).catch((err) => {
+        console.error(`Error sending ${phase} early hints:`, err)
+      })
+    }
+  } catch (err) {
+    console.error(`Error sending ${phase} early hints:`, err)
+  }
+}
+
+function getResponseLinkHeaderFilter(
+  responseLinkHeader: boolean | ResponseLinkHeaderOptions | undefined,
+): ResponseLinkHeaderFilter | undefined {
+  if (typeof responseLinkHeader !== 'object') {
+    return undefined
+  }
+
+  return responseLinkHeader.filter
+}
+
+function appendResponseLinkHeaders(opts: {
+  responseHeaders: Headers
+  entries: ReadonlyArray<ResponseLinkHeaderEntry>
+  filter?: ResponseLinkHeaderFilter
+}) {
+  for (const link of getResponseLinkHeaderEntries(opts)) {
+    opts.responseHeaders.append('Link', link)
+  }
+}
+
+function collectResponseLinkHeaderEntries(opts: {
+  phase: EarlyHintsPhase
+  event: EarlyHintsEvent
+  entries: Array<ResponseLinkHeaderEntry>
+}) {
+  for (let index = 0; index < opts.event.hints.length; index++) {
+    opts.entries.push({
+      phase: opts.phase,
+      hint: opts.event.hints[index]!,
+      link: opts.event.links[index]!,
+    })
+  }
+}
+
+function collectEarlyHintsPhase(opts: {
+  phase: EarlyHintsPhase
+  hints: ReadonlyArray<EarlyHint>
+  sentLinks: Set<string>
+  sentHints?: Array<EarlyHint>
+  onEarlyHints?: OnEarlyHints
+  responseLinkHeaderEntries?: Array<ResponseLinkHeaderEntry>
+}) {
+  const event = opts.onEarlyHints
+    ? createEarlyHintsEvent({
+        phase: opts.phase,
+        hints: opts.hints,
+        sentLinks: opts.sentLinks,
+        sentHints: opts.sentHints!,
+      })
+    : undefined
+
+  if (event) {
+    notifyEarlyHints(opts.phase, event, opts.onEarlyHints!)
+  }
+
+  if (!opts.responseLinkHeaderEntries) return
+
+  if (event) {
+    collectResponseLinkHeaderEntries({
+      phase: opts.phase,
+      event,
+      entries: opts.responseLinkHeaderEntries,
+    })
+    return
+  }
+
+  createResponseLinkHeaderEntries({
+    phase: opts.phase,
+    hints: opts.hints,
+    sentLinks: opts.sentLinks,
+    entries: opts.responseLinkHeaderEntries,
+  })
+}
+
+export function createEarlyHintsCollector(
+  opts:
+    | {
+        onEarlyHints?: OnEarlyHints
+        responseLinkHeader?: boolean | ResponseLinkHeaderOptions
+      }
+    | undefined,
+): EarlyHintsCollector | undefined {
+  if (
+    process.env.TSS_DEV_SERVER === 'true' ||
+    (!opts?.onEarlyHints && !opts?.responseLinkHeader)
+  ) {
+    return undefined
+  }
+
+  const sentLinks = new Set<string>()
+  const sentHints = opts.onEarlyHints ? new Array<EarlyHint>() : undefined
+  const responseLinkHeaderEntries = opts.responseLinkHeader
+    ? new Array<ResponseLinkHeaderEntry>()
+    : undefined
+  const responseLinkHeaderFilter = getResponseLinkHeaderFilter(
+    opts.responseLinkHeader,
+  )
+
+  return {
+    collectStatic: ({ manifest, matchedRoutes }) => {
+      if (!matchedRoutes?.length) return
+
+      collectEarlyHintsPhase({
+        phase: 'static',
+        hints: collectStaticHintsFromManifest(manifest, matchedRoutes),
+        sentLinks,
+        sentHints,
+        onEarlyHints: opts.onEarlyHints,
+        responseLinkHeaderEntries,
+      })
+    },
+    collectDynamic: (matches) => {
+      collectEarlyHintsPhase({
+        phase: 'dynamic',
+        hints: collectDynamicHintsFromMatches(matches),
+        sentLinks,
+        sentHints,
+        onEarlyHints: opts.onEarlyHints,
+        responseLinkHeaderEntries,
+      })
+    },
+    appendResponseHeaders: (headers) => {
+      if (!responseLinkHeaderEntries?.length) return
+
+      appendResponseLinkHeaders({
+        responseHeaders: headers,
+        entries: responseLinkHeaderEntries,
+        filter: responseLinkHeaderFilter,
+      })
+    },
+  }
+}

package/src/finalManifest.ts

@@ -0,0 +1,319 @@
+import {
+  buildManifestWithClientEntry,
+  resolveTransformAssetsConfig,
+  transformManifestAssets,
+} from './transformAssetUrls'
+import {
+  getStaticHandlerInlineCssDefault,
+  resolveInlineCssForRequest,
+} from './inlineCss'
+import type { Manifest } from '@tanstack/router-core'
+import type { HandlerInlineCssOption } from './inlineCss'
+import type {
+  CreateTransformAssetsContext,
+  StartManifestWithClientEntry,
+  TransformAssets,
+  TransformAssetsFn,
+} from './transformAssetUrls'
+
+export type {
+  HandlerInlineCssOption,
+  StartManifestWithClientEntry,
+  TransformAssets,
+}
+
+export interface FinalManifestOptions {
+  /**
+   * Controls whether Start inlines build-collected CSS by default at runtime.
+   *
+   * This only has an effect when the build was created with
+   * `server.build.inlineCss` enabled. Pass a callback to decide per request.
+   * `handler(request, { inlineCss })` overrides this value for that request.
+   *
+   * @default true
+   */
+  inlineCss?: HandlerInlineCssOption
+  /**
+   * Transform manifest-managed asset URLs and attributes at runtime, e.g. to
+   * prepend a CDN prefix.
+   *
+   * This covers JS preloads, CSS links, the client entry script, and URLs
+   * inside build-collected inline CSS. Asset imports used directly in
+   * components should be handled by the bundler instead.
+   */
+  transformAssets?: TransformAssets
+}
+
+type FinalManifestCacheKey = 'inline-css' | 'linked-css'
+type FinalManifestCache = Map<FinalManifestCacheKey, Promise<Manifest>>
+export type GetBaseManifest = () => Promise<StartManifestWithClientEntry>
+
+export interface FinalManifestRequestOptions {
+  request: Request
+  requestInlineCss: boolean | undefined
+  getBaseManifest: GetBaseManifest
+}
+
+interface FinalManifestTransformResolver {
+  cache: boolean
+  warmup: boolean
+  getTransformFn: (
+    ctx: CreateTransformAssetsContext,
+  ) => Promise<TransformAssetsFn | undefined>
+  clearCachedCreateTransform: () => void
+}
+
+export interface FinalManifestResolver {
+  warmup: (opts: {
+    getBaseManifest: GetBaseManifest
+  }) => Promise<Manifest> | undefined
+  resolveCached: (opts: FinalManifestRequestOptions) => Promise<Manifest>
+  resolveUncached: (opts: FinalManifestRequestOptions) => Promise<Manifest>
+}
+
+export function createCachedBaseManifestLoader(
+  loadBaseManifest: GetBaseManifest,
+): GetBaseManifest {
+  let baseManifestPromise: Promise<StartManifestWithClientEntry> | undefined
+
+  return () => {
+    if (!baseManifestPromise) {
+      baseManifestPromise = loadBaseManifest().catch((error) => {
+        baseManifestPromise = undefined
+        throw error
+      })
+    }
+
+    return baseManifestPromise
+  }
+}
+
+function createFinalManifestTransformResolver(
+  transformAssets: TransformAssets | undefined,
+  opts: { cacheCreateTransform: boolean },
+): FinalManifestTransformResolver {
+  const transformConfig =
+    transformAssets !== undefined
+      ? resolveTransformAssetsConfig(transformAssets)
+      : undefined
+  const cache = transformConfig ? transformConfig.cache : true
+  const warmup =
+    !!transformAssets &&
+    typeof transformAssets === 'object' &&
+    'warmup' in transformAssets &&
+    transformAssets.warmup === true
+
+  let cachedCreateTransformPromise: Promise<TransformAssetsFn> | undefined
+
+  const clearCachedCreateTransform = () => {
+    cachedCreateTransformPromise = undefined
+  }
+
+  return {
+    cache,
+    warmup,
+    clearCachedCreateTransform,
+    getTransformFn: async (ctx) => {
+      if (!transformConfig) return undefined
+
+      if (transformConfig.type !== 'createTransform') {
+        return transformConfig.transformFn
+      }
+
+      if (!cache || !opts.cacheCreateTransform) {
+        return transformConfig.createTransform(ctx)
+      }
+
+      if (!cachedCreateTransformPromise) {
+        cachedCreateTransformPromise = Promise.resolve(
+          transformConfig.createTransform(ctx),
+        ).catch((error) => {
+          clearCachedCreateTransform()
+          throw error
+        })
+      }
+
+      return cachedCreateTransformPromise
+    },
+  }
+}
+
+export function createFinalManifestResolver(
+  opts: FinalManifestOptions & { cacheCreateTransform: boolean },
+): FinalManifestResolver {
+  const finalManifestCache: FinalManifestCache = new Map()
+  const transformResolver = createFinalManifestTransformResolver(
+    opts.transformAssets,
+    { cacheCreateTransform: opts.cacheCreateTransform },
+  )
+  const handlerDefaultInlineCss = getStaticHandlerInlineCssDefault(
+    opts.inlineCss,
+  )
+
+  const getRequestManifestOptions = async (
+    requestOpts: FinalManifestRequestOptions,
+  ) => {
+    const transformFn = await transformResolver.getTransformFn({
+      warmup: false,
+      request: requestOpts.request,
+    })
+    const inlineCss = await resolveInlineCssForRequest({
+      request: requestOpts.request,
+      handlerInlineCss: opts.inlineCss,
+      requestInlineCss: requestOpts.requestInlineCss,
+    })
+
+    return {
+      getBaseManifest: requestOpts.getBaseManifest,
+      transformFn,
+      cache: transformResolver.cache,
+      inlineCss,
+    }
+  }
+
+  const resolveRequest = async (
+    requestOpts: FinalManifestRequestOptions,
+    cache: FinalManifestCache | undefined,
+  ) => {
+    return resolveFinalManifest({
+      ...(await getRequestManifestOptions(requestOpts)),
+      finalManifestCache: cache,
+    })
+  }
+
+  return {
+    warmup: ({ getBaseManifest }) =>
+      warmupFinalManifest({
+        enabled: transformResolver.warmup,
+        handlerDefaultInlineCss,
+        cache: transformResolver.cache,
+        finalManifestCache,
+        getBaseManifest,
+        getTransformFn: () =>
+          transformResolver.getTransformFn({ warmup: true }),
+        onError: transformResolver.clearCachedCreateTransform,
+      }),
+    resolveCached: (requestOpts) =>
+      resolveRequest(requestOpts, finalManifestCache),
+    resolveUncached: (requestOpts) => resolveRequest(requestOpts, undefined),
+  }
+}
+
+function getFinalManifestCacheKey(inlineCss: boolean): FinalManifestCacheKey {
+  return inlineCss ? 'inline-css' : 'linked-css'
+}
+
+function cacheFinalManifestPromise(
+  cachedFinalManifestPromises: FinalManifestCache,
+  cacheKey: FinalManifestCacheKey,
+  promise: Promise<Manifest>,
+): Promise<Manifest> {
+  const cachedFinalManifestPromise = promise.catch((error) => {
+    if (
+      cachedFinalManifestPromises.get(cacheKey) === cachedFinalManifestPromise
+    ) {
+      cachedFinalManifestPromises.delete(cacheKey)
+    }
+    throw error
+  })
+
+  cachedFinalManifestPromises.set(cacheKey, cachedFinalManifestPromise)
+  return cachedFinalManifestPromise
+}
+
+function getOrCreateCachedFinalManifestPromise(
+  cachedFinalManifestPromises: FinalManifestCache,
+  cacheKey: FinalManifestCacheKey,
+  computeFinalManifest: () => Promise<Manifest>,
+): Promise<Manifest> {
+  const cachedFinalManifestPromise = cachedFinalManifestPromises.get(cacheKey)
+  if (cachedFinalManifestPromise) {
+    return cachedFinalManifestPromise
+  }
+
+  return cacheFinalManifestPromise(
+    cachedFinalManifestPromises,
+    cacheKey,
+    Promise.resolve().then(computeFinalManifest),
+  )
+}
+
+async function buildFinalManifest(opts: {
+  base: StartManifestWithClientEntry
+  transformFn: TransformAssetsFn | undefined
+  inlineCss: boolean
+}): Promise<Manifest> {
+  return opts.transformFn
+    ? await transformManifestAssets(opts.base, opts.transformFn, {
+        inlineCss: opts.inlineCss,
+      })
+    : buildManifestWithClientEntry(opts.base, { inlineCss: opts.inlineCss })
+}
+
+async function resolveFinalManifest(opts: {
+  getBaseManifest: () => Promise<StartManifestWithClientEntry>
+  transformFn: TransformAssetsFn | undefined
+  cache: boolean
+  inlineCss: boolean
+  finalManifestCache?: FinalManifestCache
+}): Promise<Manifest> {
+  const computeFinalManifest = async () => {
+    return buildFinalManifest({
+      base: await opts.getBaseManifest(),
+      transformFn: opts.transformFn,
+      inlineCss: opts.inlineCss,
+    })
+  }
+
+  if (opts.finalManifestCache && (!opts.transformFn || opts.cache)) {
+    return getOrCreateCachedFinalManifestPromise(
+      opts.finalManifestCache,
+      getFinalManifestCacheKey(opts.inlineCss),
+      computeFinalManifest,
+    )
+  }
+
+  return computeFinalManifest()
+}
+
+function warmupFinalManifest(opts: {
+  enabled: boolean
+  handlerDefaultInlineCss: boolean | undefined
+  cache: boolean
+  finalManifestCache: FinalManifestCache
+  getBaseManifest: () => Promise<StartManifestWithClientEntry>
+  getTransformFn: () => Promise<TransformAssetsFn | undefined>
+  onError?: () => void
+}): Promise<Manifest> | undefined {
+  if (
+    !opts.enabled ||
+    opts.handlerDefaultInlineCss === undefined ||
+    !opts.cache
+  ) {
+    return undefined
+  }
+
+  const inlineCss = opts.handlerDefaultInlineCss
+  const warmupPromise = getOrCreateCachedFinalManifestPromise(
+    opts.finalManifestCache,
+    getFinalManifestCacheKey(inlineCss),
+    async () => {
+      const [base, transformFn] = await Promise.all([
+        opts.getBaseManifest(),
+        opts.getTransformFn(),
+      ])
+
+      return buildFinalManifest({
+        base,
+        transformFn,
+        inlineCss,
+      })
+    },
+  )
+
+  if (opts.onError) {
+    void warmupPromise.catch(opts.onError)
+  }
+
+  return warmupPromise
+}

package/src/index.tsx

@@ -9,12 +9,8 @@ export type {
   TransformAssetsObjectShorthand,
   TransformAssetsCrossOriginConfig,
   TransformAssetResult,
-  TransformAssetUrls,
-  TransformAssetUrlsFn,
-  TransformAssetUrlsContext,
-  TransformAssetUrlsOptions,
-  AssetUrlType,
   TransformAssetKind,
+  CreateTransformAssetsContext,
 } from './transformAssetUrls'
 
 export {

package/src/inlineCss.ts

@@ -0,0 +1,31 @@
+import type { Awaitable } from '@tanstack/router-core'
+
+export type HandlerInlineCssOption =
+  | boolean
+  | ((ctx: { request: Request }) => Awaitable<boolean>)
+
+export function getStaticHandlerInlineCssDefault(
+  handlerInlineCss: HandlerInlineCssOption | undefined,
+) {
+  if (typeof handlerInlineCss === 'function') {
+    return undefined
+  }
+
+  return handlerInlineCss ?? true
+}
+
+export async function resolveInlineCssForRequest(opts: {
+  request: Request
+  handlerInlineCss: HandlerInlineCssOption | undefined
+  requestInlineCss: boolean | undefined
+}) {
+  if (opts.requestInlineCss !== undefined) {
+    return opts.requestInlineCss
+  }
+
+  if (typeof opts.handlerInlineCss === 'function') {
+    return await opts.handlerInlineCss({ request: opts.request })
+  }
+
+  return opts.handlerInlineCss ?? true
+}

package/src/request-handler.ts

@@ -45,7 +45,19 @@ type EarlyHintsOptions = {
   responseLinkHeader?: boolean | ResponseLinkHeaderOptions
 }
 
+type InlineCssOptions = {
+  /**
+   * Controls whether Start inlines build-collected CSS for this request.
+   *
+   * This only has an effect when the build was created with
+   * `server.build.inlineCss` enabled. Defaults to `true` so builds with inline
+   * CSS enabled continue to inline CSS unless a request opts out.
+   */
+  inlineCss?: boolean
+}
+
 export type RequestOptions<TRegister> = EarlyHintsOptions &
+  InlineCssOptions &
   (TRegister extends {
     server: { requestContext: infer TRequestContext }
   }