htmlFallbackMiddleware() — vite Function Reference

Architecture documentation for the htmlFallbackMiddleware() function in htmlFallback.ts from the vite codebase.

Function typescript ViteCore ConfigEngine calls 3 called by 2

Entity Profile

ViteCore→ ConfigEngine→ htmlFallbackMiddleware() — vite Function Reference

Dependency Diagram

graph TD
  78e76dd8_dc3d_71e9_dcb6_3683bef37b56["htmlFallbackMiddleware()"]
  56b9dfe1_f57e_b16b_3e97_b64544e748cd["htmlFallback.ts"]
  78e76dd8_dc3d_71e9_dcb6_3683bef37b56 -->|defined in| 56b9dfe1_f57e_b16b_3e97_b64544e748cd
  5c50110b_5c76_c14f_b1dd_3efd3df7f375["preview()"]
  5c50110b_5c76_c14f_b1dd_3efd3df7f375 -->|calls| 78e76dd8_dc3d_71e9_dcb6_3683bef37b56
  24ecf2a1_3c09_d451_76f3_9485b4e993f8["_createServer()"]
  24ecf2a1_3c09_d451_76f3_9485b4e993f8 -->|calls| 78e76dd8_dc3d_71e9_dcb6_3683bef37b56
  010d4483_95f2_b44c_22ac_99a40a3261a6["has()"]
  78e76dd8_dc3d_71e9_dcb6_3683bef37b56 -->|calls| 010d4483_95f2_b44c_22ac_99a40a3261a6
  10b9dea8_362c_1af2_93be_afa4dd9aed9e["cleanUrl()"]
  78e76dd8_dc3d_71e9_dcb6_3683bef37b56 -->|calls| 10b9dea8_362c_1af2_93be_afa4dd9aed9e
  c9db8630_93b3_267d_8e26_8b62626a11ca["joinUrlSegments()"]
  78e76dd8_dc3d_71e9_dcb6_3683bef37b56 -->|calls| c9db8630_93b3_267d_8e26_8b62626a11ca
  style 78e76dd8_dc3d_71e9_dcb6_3683bef37b56 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/vite/src/node/server/middlewares/htmlFallback.ts lines 11–91

export function htmlFallbackMiddleware(
  root: string,
  spaFallback: boolean,
  clientEnvironment?: DevEnvironment,
): Connect.NextHandleFunction {
  const memoryFiles =
    clientEnvironment instanceof FullBundleDevEnvironment
      ? clientEnvironment.memoryFiles
      : undefined

  function checkFileExists(relativePath: string) {
    return (
      memoryFiles?.has(
        relativePath.slice(1), // remove first /
      ) ?? fs.existsSync(path.join(root, relativePath))
    )
  }

  // Keep the named function. The name is visible in debug logs via `DEBUG=connect:dispatcher ...`
  return function viteHtmlFallbackMiddleware(req, _res, next) {
    if (
      // Only accept GET or HEAD
      (req.method !== 'GET' && req.method !== 'HEAD') ||
      // Exclude default favicon requests
      req.url === '/favicon.ico' ||
      // Require Accept: text/html or */*
      !(
        req.headers.accept === undefined || // equivalent to `Accept: */*`
        req.headers.accept === '' || // equivalent to `Accept: */*`
        req.headers.accept.includes('text/html') ||
        req.headers.accept.includes('*/*')
      )
    ) {
      return next()
    }

    const url = cleanUrl(req.url!)
    let pathname
    try {
      pathname = decodeURIComponent(url)
    } catch {
      // ignore malformed URI
      return next()
    }

    // .html files are not handled by serveStaticMiddleware
    // so we need to check if the file exists
    if (pathname.endsWith('.html')) {
      if (checkFileExists(pathname)) {
        debug?.(`Rewriting ${req.method} ${req.url} to ${url}`)
        req.url = url
        return next()
      }
    }
    // trailing slash should check for fallback index.html
    else if (pathname.endsWith('/')) {
      if (checkFileExists(joinUrlSegments(pathname, 'index.html'))) {
        const newUrl = url + 'index.html'
        debug?.(`Rewriting ${req.method} ${req.url} to ${newUrl}`)
        req.url = newUrl
        return next()
      }
    }
    // non-trailing slash should check for fallback .html
    else {
      if (checkFileExists(pathname + '.html')) {
        const newUrl = url + '.html'
        debug?.(`Rewriting ${req.method} ${req.url} to ${newUrl}`)
        req.url = newUrl
        return next()
      }
    }

    if (spaFallback) {
      debug?.(`Rewriting ${req.method} ${req.url} to /index.html`)
      req.url = '/index.html'
    }

    next()
  }
}