@tanstack/start-plugin-core 1.167.35 → 1.169.0

package/src/{import-protection-plugin → import-protection}/virtualModules.ts

@@ -1,100 +1,15 @@
-import { resolveViteId } from '../utils'
-import { VITE_ENVIRONMENT_NAMES } from '../constants'
-import { isValidExportName } from './rewriteDeniedImports'
+import {
+  MARKER_PREFIX,
+  MOCK_BUILD_PREFIX,
+  MOCK_EDGE_PREFIX,
+  MOCK_MODULE_ID,
+  MOCK_RUNTIME_PREFIX,
+} from './constants'
+import { isValidExportName } from './analysis'
 import { CLIENT_ENV_SUGGESTIONS } from './trace'
-import { VITE_BROWSER_VIRTUAL_PREFIX } from './constants'
 import { relativizePath } from './utils'
 import type { ViolationInfo } from './trace'
 
-export const MOCK_MODULE_ID = 'tanstack-start-import-protection:mock'
-const RESOLVED_MOCK_MODULE_ID = resolveViteId(MOCK_MODULE_ID)
-
-/**
- * Per-violation mock prefix used in build+error mode.
- * Each deferred violation gets a unique ID so we can check which ones
- * survived tree-shaking in `generateBundle`.
- */
-export const MOCK_BUILD_PREFIX = 'tanstack-start-import-protection:mock:build:'
-const RESOLVED_MOCK_BUILD_PREFIX = resolveViteId(MOCK_BUILD_PREFIX)
-
-export const MOCK_EDGE_PREFIX = 'tanstack-start-import-protection:mock-edge:'
-const RESOLVED_MOCK_EDGE_PREFIX = resolveViteId(MOCK_EDGE_PREFIX)
-
-export const MOCK_RUNTIME_PREFIX =
-  'tanstack-start-import-protection:mock-runtime:'
-const RESOLVED_MOCK_RUNTIME_PREFIX = resolveViteId(MOCK_RUNTIME_PREFIX)
-
-const MARKER_PREFIX = 'tanstack-start-import-protection:marker:'
-const RESOLVED_MARKER_PREFIX = resolveViteId(MARKER_PREFIX)
-
-const RESOLVED_MARKER_SERVER_ONLY = resolveViteId(`${MARKER_PREFIX}server-only`)
-const RESOLVED_MARKER_CLIENT_ONLY = resolveViteId(`${MARKER_PREFIX}client-only`)
-
-export function resolvedMarkerVirtualModuleId(
-  kind: 'server' | 'client',
-): string {
-  return kind === 'server'
-    ? RESOLVED_MARKER_SERVER_ONLY
-    : RESOLVED_MARKER_CLIENT_ONLY
-}
-
-/**
- * Convenience list for plugin `load` filters/handlers.
- *
- * Vite/Rollup call `load(id)` with the *resolved* virtual id (prefixed by `\0`).
- * `resolveId(source)` sees the *unresolved* id/prefix (without `\0`).
- */
-export function getResolvedVirtualModuleMatchers(): ReadonlyArray<string> {
-  return RESOLVED_VIRTUAL_MODULE_MATCHERS
-}
-
-const RESOLVED_VIRTUAL_MODULE_MATCHERS = [
-  RESOLVED_MOCK_MODULE_ID,
-  RESOLVED_MOCK_BUILD_PREFIX,
-  RESOLVED_MOCK_EDGE_PREFIX,
-  RESOLVED_MOCK_RUNTIME_PREFIX,
-  RESOLVED_MARKER_PREFIX,
-] as const
-
-const RESOLVE_PREFIX_PAIRS = [
-  [MOCK_EDGE_PREFIX, RESOLVED_MOCK_EDGE_PREFIX],
-  [MOCK_RUNTIME_PREFIX, RESOLVED_MOCK_RUNTIME_PREFIX],
-  [MOCK_BUILD_PREFIX, RESOLVED_MOCK_BUILD_PREFIX],
-  [MARKER_PREFIX, RESOLVED_MARKER_PREFIX],
-] as const
-
-/**
- * Resolve import-protection's internal virtual module IDs.
- *
- * `resolveId(source)` sees *unresolved* ids/prefixes (no `\0`).
- * Returning a resolved id (with `\0`) ensures Vite/Rollup route it to `load`.
- */
-export function resolveInternalVirtualModuleId(
-  source: string,
-): string | undefined {
-  if (source.startsWith(VITE_BROWSER_VIRTUAL_PREFIX)) {
-    return resolveInternalVirtualModuleId(
-      `\0${source.slice(VITE_BROWSER_VIRTUAL_PREFIX.length)}`,
-    )
-  }
-
-  if (source === MOCK_MODULE_ID || source === RESOLVED_MOCK_MODULE_ID) {
-    return RESOLVED_MOCK_MODULE_ID
-  }
-
-  for (const [unresolvedPrefix, resolvedPrefix] of RESOLVE_PREFIX_PAIRS) {
-    if (source.startsWith(unresolvedPrefix)) {
-      return resolveViteId(source)
-    }
-
-    if (source.startsWith(resolvedPrefix)) {
-      return source
-    }
-  }
-
-  return undefined
-}
-
 function toBase64Url(input: string): string {
   return Buffer.from(input, 'utf8').toString('base64url')
 }
@@ -105,10 +20,6 @@ function fromBase64Url(input: string): string {
 
 type MockAccessMode = 'error' | 'warn' | 'off'
 
-/**
- * Compact runtime suggestion text for browser console, derived from
- * {@link CLIENT_ENV_SUGGESTIONS} so there's a single source of truth.
- */
 export const RUNTIME_SUGGESTION_TEXT =
   'Fix: ' +
   CLIENT_ENV_SUGGESTIONS.join('. ') +
@@ -120,7 +31,7 @@ export function mockRuntimeModuleIdFromViolation(
   root: string,
 ): string {
   if (mode === 'off') return MOCK_MODULE_ID
-  if (info.env !== VITE_ENVIRONMENT_NAMES.client) return MOCK_MODULE_ID
+  if (info.env !== 'client') return MOCK_MODULE_ID
 
   const rel = (p: string) => relativizePath(p, root)
   const trace = info.trace.map((s) => {
@@ -136,6 +47,7 @@ export function mockRuntimeModuleIdFromViolation(
     trace,
     mode,
   }
+
   return `${MOCK_RUNTIME_PREFIX}${toBase64Url(JSON.stringify(payload))}`
 }
 
@@ -147,17 +59,6 @@ export function makeMockEdgeModuleId(
   return `${MOCK_EDGE_PREFIX}${toBase64Url(JSON.stringify(payload))}`
 }
 
-/**
- * Generate a recursive Proxy-based mock module.
- *
- * When `diagnostics` is provided, the generated code includes a `__report`
- * function that logs runtime warnings/errors when the mock is actually used
- * (property access for primitive coercion, calls, construction, sets).
- *
- * When `diagnostics` is omitted, the mock is completely silent — suitable
- * for base mock modules (e.g. `MOCK_MODULE_ID` or per-violation build mocks)
- * that are consumed by mock-edge modules providing explicit named exports.
- */
 function generateMockCode(diagnostics?: {
   meta: {
     env: string
@@ -203,7 +104,6 @@ function __report(action, accessPath) {
 `
     : ''
 
-  // Diagnostic-only traps for primitive coercion, set
   const diagGetTraps = hasDiag
     ? `
       if (prop === Symbol.toPrimitive) {
@@ -276,19 +176,10 @@ export function loadSilentMockModule(): { code: string } {
   return { code: generateMockCode() }
 }
 
-/**
- * Filter export names to valid, non-default names.
- */
 function filterExportNames(exports: ReadonlyArray<string>): Array<string> {
   return exports.filter((n) => n.length > 0 && n !== 'default')
 }
 
-/**
- * Generate ESM export lines that re-export named properties from `mock`.
- *
- * Produces `export const foo = mock.foo;` for valid identifiers and
- * string-keyed re-exports for non-identifier names.
- */
 function generateExportLines(names: ReadonlyArray<string>): Array<string> {
   const lines: Array<string> = []
   const stringExports: Array<{ alias: string; name: string }> = []
@@ -314,17 +205,6 @@ function generateExportLines(names: ReadonlyArray<string>): Array<string> {
   return lines
 }
 
-/**
- * Generate a self-contained mock module with explicit named exports.
- *
- * Used by the transform hook's "self-denial" check: when a denied file
- * (e.g. `.server.ts` in the client environment) is transformed, its entire
- * content is replaced with this mock module.  This avoids returning virtual
- * module IDs from `resolveId`, which prevents cross-environment cache
- * contamination from third-party resolver plugins.
- *
- * The generated code is side-effect-free and tree-shakeable.
- */
 export function generateSelfContainedMockModule(exportNames: Array<string>): {
   code: string
 } {
@@ -338,18 +218,6 @@ ${exportLines.join('\n')}
   }
 }
 
-/**
- * Generate a dev-mode mock module for self-denial transforms.
- *
- * Similar to `loadMockEdgeModule` but takes export names and a runtime ID
- * directly (instead of parsing them from a base64url-encoded payload).
- * Used by the transform hook when a denied file (e.g. `.server.ts` in
- * the client environment) is replaced in dev mode.
- *
- * The generated module imports mock-runtime for runtime diagnostics
- * (error/warn on property access) and re-exports explicit named exports
- * so that `import { foo } from './denied.server'` works.
- */
 export function generateDevSelfDenialModule(
   exportNames: Array<string>,
   runtimeId: string,
@@ -367,18 +235,18 @@ export default mock;
 
 export function loadMockEdgeModule(encodedPayload: string): { code: string } {
   let payload: { exports?: Array<string>; runtimeId?: string }
+
   try {
     payload = JSON.parse(fromBase64Url(encodedPayload)) as typeof payload
   } catch {
     payload = { exports: [] }
   }
-  const names = filterExportNames(payload.exports ?? [])
 
-  const runtimeId: string =
+  const names = filterExportNames(payload.exports ?? [])
+  const runtimeId =
     typeof payload.runtimeId === 'string' && payload.runtimeId.length > 0
       ? payload.runtimeId
       : MOCK_MODULE_ID
-
   const exportLines = generateExportLines(names)
 
   return {
@@ -399,6 +267,7 @@ export function loadMockRuntimeModule(encodedPayload: string): {
     specifier?: string
     trace?: Array<unknown>
   }
+
   try {
     payload = JSON.parse(fromBase64Url(encodedPayload)) as typeof payload
   } catch {
@@ -408,14 +277,17 @@ export function loadMockRuntimeModule(encodedPayload: string): {
   const mode: 'error' | 'warn' | 'off' =
     payload.mode === 'warn' || payload.mode === 'off' ? payload.mode : 'error'
 
-  const meta = {
-    env: String(payload.env ?? ''),
-    importer: String(payload.importer ?? ''),
-    specifier: String(payload.specifier ?? ''),
-    trace: Array.isArray(payload.trace) ? payload.trace : [],
+  return {
+    code: generateMockCode({
+      meta: {
+        env: String(payload.env ?? ''),
+        importer: String(payload.importer ?? ''),
+        specifier: String(payload.specifier ?? ''),
+        trace: Array.isArray(payload.trace) ? payload.trace : [],
+      },
+      mode,
+    }),
   }
-
-  return { code: generateMockCode({ meta, mode }) }
 }
 
 const MARKER_MODULE_RESULT = { code: 'export {}' } as const
@@ -424,29 +296,10 @@ export function loadMarkerModule(): { code: string } {
   return MARKER_MODULE_RESULT
 }
 
-export function loadResolvedVirtualModule(
-  id: string,
-): { code: string } | undefined {
-  if (id === RESOLVED_MOCK_MODULE_ID) {
-    return loadSilentMockModule()
-  }
-
-  // Per-violation build mock modules — same silent mock code
-  if (id.startsWith(RESOLVED_MOCK_BUILD_PREFIX)) {
-    return loadSilentMockModule()
-  }
-
-  if (id.startsWith(RESOLVED_MOCK_EDGE_PREFIX)) {
-    return loadMockEdgeModule(id.slice(RESOLVED_MOCK_EDGE_PREFIX.length))
-  }
-
-  if (id.startsWith(RESOLVED_MOCK_RUNTIME_PREFIX)) {
-    return loadMockRuntimeModule(id.slice(RESOLVED_MOCK_RUNTIME_PREFIX.length))
-  }
-
-  if (id.startsWith(RESOLVED_MARKER_PREFIX)) {
-    return loadMarkerModule()
-  }
-
-  return undefined
+export {
+  MARKER_PREFIX,
+  MOCK_BUILD_PREFIX,
+  MOCK_EDGE_PREFIX,
+  MOCK_MODULE_ID,
+  MOCK_RUNTIME_PREFIX,
 }

package/src/index.ts

@@ -1,10 +1,3 @@
 export type { TanStackStartInputConfig } from './schema'
 export type { TanStackStartCoreOptions } from './types'
-export type {
-  TanStackStartVitePluginCoreOptions,
-  ViteRscForwardSsrResolverStrategy,
-} from './vite/types'
-export type { TanStackStartViteInputConfig } from './vite/schema'
-export { START_ENVIRONMENT_NAMES, VITE_ENVIRONMENT_NAMES } from './constants'
-export { createVirtualModule } from './vite/createVirtualModule'
-export { tanStackStartVite } from './vite/plugin'
+export { START_ENVIRONMENT_NAMES } from './constants'

package/src/post-build.ts

@@ -0,0 +1,64 @@
+import { HEADERS } from '@tanstack/start-server-core'
+import { buildSitemap } from './build-sitemap'
+import type { TanStackStartOutputConfig } from './schema'
+
+export interface StartPostBuildAdapter {
+  getClientOutputDirectory: () => string
+  prerender: (startConfig: TanStackStartOutputConfig) => Promise<void>
+}
+
+export async function postBuild({
+  startConfig,
+  adapter,
+}: {
+  startConfig: TanStackStartOutputConfig
+  adapter: StartPostBuildAdapter
+}) {
+  if (startConfig.prerender?.enabled !== false) {
+    startConfig.prerender = {
+      ...startConfig.prerender,
+      enabled:
+        startConfig.prerender?.enabled ??
+        startConfig.pages.some((d) =>
+          typeof d === 'string' ? false : !!d.prerender?.enabled,
+        ),
+    }
+  }
+
+  if (startConfig.spa?.enabled) {
+    startConfig.prerender = {
+      ...startConfig.prerender,
+      enabled: true,
+    }
+
+    const maskUrl = new URL(startConfig.spa.maskPath, 'http://localhost')
+    if (maskUrl.origin !== 'http://localhost') {
+      throw new Error('spa.maskPath must be a path (no protocol/host)')
+    }
+
+    startConfig.pages.push({
+      path: maskUrl.toString().replace('http://localhost', ''),
+      prerender: {
+        ...startConfig.spa.prerender,
+        headers: {
+          ...startConfig.spa.prerender.headers,
+          [HEADERS.TSS_SHELL]: 'true',
+        },
+      },
+      sitemap: {
+        exclude: true,
+      },
+    })
+  }
+
+  if (startConfig.prerender.enabled) {
+    await adapter.prerender(startConfig)
+  }
+
+  if (startConfig.sitemap?.enabled) {
+    buildSitemap({
+      startConfig,
+      publicDir: adapter.getClientOutputDirectory(),
+    })
+  }
+}

package/src/prerender.ts

@@ -0,0 +1,292 @@
+import { promises as fsp } from 'node:fs'
+import os from 'node:os'
+import path from 'pathe'
+import { joinURL, withBase, withTrailingSlash, withoutBase } from 'ufo'
+import { createLogger } from './utils'
+import { Queue } from './queue'
+import type { Page, TanStackStartOutputConfig } from './schema'
+
+const DEFAULT_RETRY_DELAY = 500
+
+export interface PrerenderHandler {
+  getClientOutputDirectory: () => string
+  request: (path: string, options?: RequestInit) => Promise<Response>
+  close?: () => Promise<void>
+}
+
+export async function prerender({
+  startConfig,
+  handler,
+}: {
+  startConfig: TanStackStartOutputConfig
+  handler: PrerenderHandler
+}) {
+  const logger = createLogger('prerender')
+  logger.info('Prerendering pages...')
+
+  if (startConfig.prerender?.enabled) {
+    let pages = startConfig.pages.length ? startConfig.pages : [{ path: '/' }]
+
+    if (startConfig.prerender.autoStaticPathsDiscovery ?? true) {
+      const pagesMap = new Map(pages.map((item) => [item.path, item]))
+      const discoveredPages = globalThis.TSS_PRERENDABLE_PATHS || []
+
+      for (const page of discoveredPages) {
+        if (!pagesMap.has(page.path)) {
+          pagesMap.set(page.path, page)
+        }
+      }
+
+      pages = Array.from(pagesMap.values())
+    }
+
+    startConfig.pages = pages
+  }
+
+  const routerBasePath = joinURL('/', startConfig.router.basepath ?? '')
+  const routerBaseUrl = new URL(routerBasePath, 'http://localhost')
+
+  startConfig.pages = validateAndNormalizePrerenderPages(
+    startConfig.pages,
+    routerBaseUrl,
+  )
+
+  try {
+    const pages = await prerenderPages({
+      outputDir: handler.getClientOutputDirectory(),
+    })
+
+    logger.info(`Prerendered ${pages.length} pages:`)
+    pages.forEach((page) => {
+      logger.info(`- ${page}`)
+    })
+  } catch (error) {
+    logger.error(error)
+    throw error
+  } finally {
+    await handler.close?.()
+  }
+
+  function extractLinks(html: string): Array<string> {
+    const linkRegex = /<a[^>]+href=["']([^"']+)["'][^>]*>/g
+    const links: Array<string> = []
+    let match: RegExpExecArray | null
+
+    while ((match = linkRegex.exec(html)) !== null) {
+      const href = match[1]
+      if (href && (href.startsWith('/') || href.startsWith('./'))) {
+        links.push(href)
+      }
+    }
+
+    return links
+  }
+
+  async function prerenderPages({ outputDir }: { outputDir: string }) {
+    const seen = new Set<string>()
+    const prerendered = new Set<string>()
+    const retriesByPath = new Map<string, number>()
+    const concurrency = startConfig.prerender?.concurrency ?? os.cpus().length
+    logger.info(`Concurrency: ${concurrency}`)
+    const queue = new Queue({ concurrency })
+    const routerBasePath = joinURL('/', startConfig.router.basepath ?? '')
+    const routerBaseUrl = new URL(routerBasePath, 'http://localhost')
+
+    startConfig.pages = validateAndNormalizePrerenderPages(
+      startConfig.pages,
+      routerBaseUrl,
+    )
+
+    startConfig.pages.forEach((page) => addCrawlPageTask(page))
+
+    if (queue.isSettled()) {
+      logger.info('No pages matched prerender filter; skipping.')
+      return Array.from(prerendered)
+    }
+
+    await queue.start()
+
+    return Array.from(prerendered)
+
+    function addCrawlPageTask(page: Page) {
+      if (seen.has(page.path)) return
+
+      seen.add(page.path)
+
+      if (page.fromCrawl) {
+        startConfig.pages.push(page)
+      }
+
+      if (!(page.prerender?.enabled ?? true)) return
+
+      if (
+        startConfig.prerender?.filter &&
+        !startConfig.prerender.filter(page)
+      ) {
+        return
+      }
+
+      const prerenderOptions = {
+        ...startConfig.prerender,
+        ...page.prerender,
+      }
+
+      queue.add(async () => {
+        logger.info(`Crawling: ${page.path}`)
+        const retries = retriesByPath.get(page.path) || 0
+
+        try {
+          const res = await requestWithRedirects(
+            withTrailingSlash(withBase(page.path, routerBasePath)),
+            {
+              headers: {
+                ...(prerenderOptions.headers ?? {}),
+              },
+            },
+            prerenderOptions.maxRedirects,
+          )
+
+          if (!res.ok) {
+            if (isRedirectResponse(res)) {
+              logger.warn(`Max redirects reached for ${page.path}`)
+            }
+
+            throw new Error(`Failed to fetch ${page.path}: ${res.statusText}`, {
+              cause: res,
+            })
+          }
+
+          const cleanPagePath = (
+            prerenderOptions.outputPath || page.path
+          ).split(/[?#]/)[0]!
+
+          const contentType = res.headers.get('content-type') || ''
+          const isImplicitHTML =
+            !cleanPagePath.endsWith('.html') && contentType.includes('html')
+
+          const routeWithIndex = cleanPagePath.endsWith('/')
+            ? cleanPagePath + 'index'
+            : cleanPagePath
+
+          const isSpaShell =
+            startConfig.spa?.prerender.outputPath === cleanPagePath
+
+          let htmlPath: string
+          if (isSpaShell) {
+            htmlPath = cleanPagePath + '.html'
+          } else if (
+            cleanPagePath.endsWith('/') ||
+            (prerenderOptions.autoSubfolderIndex ?? true)
+          ) {
+            htmlPath = joinURL(cleanPagePath, 'index.html')
+          } else {
+            htmlPath = cleanPagePath + '.html'
+          }
+
+          const filename = withoutBase(
+            isImplicitHTML ? htmlPath : routeWithIndex,
+            routerBasePath,
+          )
+
+          const html = await res.text()
+          const filepath = path.join(outputDir, filename)
+
+          await fsp.mkdir(path.dirname(filepath), {
+            recursive: true,
+          })
+
+          await fsp.writeFile(filepath, html)
+
+          prerendered.add(page.path)
+
+          const newPage = await prerenderOptions.onSuccess?.({ page, html })
+
+          if (newPage) {
+            Object.assign(page, newPage)
+          }
+
+          if (prerenderOptions.crawlLinks ?? true) {
+            const links = extractLinks(html)
+            for (const link of links) {
+              addCrawlPageTask({ path: link, fromCrawl: true })
+            }
+          }
+        } catch (error) {
+          if (retries < (prerenderOptions.retryCount ?? 0)) {
+            const retryDelay = normalizeRetryDelay(prerenderOptions.retryDelay)
+            logger.warn(
+              `Encountered error, retrying: ${page.path} in ${retryDelay}ms`,
+            )
+            await new Promise((resolve) => setTimeout(resolve, retryDelay))
+            retriesByPath.set(page.path, retries + 1)
+            addCrawlPageTask(page)
+          } else if (prerenderOptions.failOnError ?? true) {
+            throw error
+          }
+        }
+      })
+    }
+  }
+
+  function normalizeRetryDelay(value: number | undefined): number {
+    const retryDelay = Number(value)
+
+    if (!Number.isFinite(retryDelay) || retryDelay < 0) {
+      return DEFAULT_RETRY_DELAY
+    }
+
+    return Math.trunc(retryDelay)
+  }
+
+  async function requestWithRedirects(
+    path: string,
+    options?: RequestInit,
+    maxRedirects: number = 5,
+  ): Promise<Response> {
+    const response = await handler.request(path, options)
+
+    if (isRedirectResponse(response) && maxRedirects > 0) {
+      const location = response.headers.get('location')!
+
+      if (location.startsWith('http://localhost') || location.startsWith('/')) {
+        const nextPath = location.replace('http://localhost', '')
+        return requestWithRedirects(nextPath, options, maxRedirects - 1)
+      }
+
+      logger.warn(`Skipping redirect to external location: ${location}`)
+    }
+
+    return response
+  }
+}
+
+function isRedirectResponse(res: Response) {
+  return res.status >= 300 && res.status < 400 && res.headers.get('location')
+}
+
+export function validateAndNormalizePrerenderPages(
+  pages: Array<Page>,
+  routerBaseUrl: URL,
+): Array<Page> {
+  return pages.map((page) => {
+    let url: URL
+    try {
+      url = new URL(page.path, routerBaseUrl)
+    } catch (err) {
+      throw new Error(`prerender page path must be relative: ${page.path}`, {
+        cause: err,
+      })
+    }
+
+    if (url.origin !== 'http://localhost') {
+      throw new Error(`prerender page path must be relative: ${page.path}`)
+    }
+
+    const decodedPathname = decodeURIComponent(url.pathname)
+
+    return {
+      ...page,
+      path: decodedPathname + url.search + url.hash,
+    }
+  })
+}