Static Site Generation

Overview

Static site generation (SSG) in Hono compiles application routes into static HTML assets and files through programmatic orchestrators like toSSG and generator functions such as fetchRoutesContent. By inspecting registered application endpoints, expanding parameter sets, and executing requests within isolated runtime contexts, Hono bridges dynamic server routing with flat-file deployment pipelines. Sources: src/helper/ssg/ssg.ts:205-221, src/helper/ssg/ssg.ts:368-372

Generation Pipeline and Lifecycle

Execution Flow and Orchestration

The static site generation lifecycle is coordinated by the public toSSG orchestrator and the underlying generator fetchRoutesContent. When invoked with a Hono application, file system module, and optional configuration parameters, toSSG initializes hook collections and plugin pipelines, defaulting to defaultPlugin when no custom plugins are supplied. Sources: src/helper/ssg/ssg.ts:368-372

Sources: src/helper/ssg/ssg.ts:205-334, src/helper/ssg/ssg.ts:368-397

Concurrency Management and Output Writing

Execution tasks across routes and requests are managed by a pool created via createPool using the concurrency option defined in ToSSGOptions. As content generators yield route payloads, saveContentToFile tracks created directories within a module-scoped createdDirs set to avoid redundant directory creation calls during file writing. Sources: src/helper/ssg/ssg.ts:195-195, src/helper/ssg/ssg.ts:223-223, src/helper/ssg/ssg.ts:309-327

Sources: src/helper/ssg/ssg.ts:195-197, src/helper/ssg/ssg.ts:309-314, src/helper/ssg/ssg.ts:372-372

Route Filtering and Parameter Expansion

Route Inspection and Filtering

The static generation pipeline begins by examining the application's registered route table via filterStaticGenerateRoutes. This utility reduces hono.routes by inspecting each route's HTTP method and handler type, retaining only endpoints capable of serving static content. Specifically, it selects routes registered with the GET method or METHOD_NAME_ALL whose target handler is not classified as middleware. Sources: src/helper/ssg/utils.ts:61-71

Dynamic Parameter Detection and Expansion

Once static routes are filtered, fetchRoutesContent evaluates each route path for dynamic segments using isDynamicRoute. A path is classified as dynamic if any of its slash-separated segments start with a colon (:) or contain a wildcard (*). Sources: src/helper/ssg/ssg.ts:225-249, src/helper/ssg/utils.ts:73-75

Sources: src/helper/ssg/ssg.ts:245-269, src/helper/ssg/utils.ts:73-75

Static Generation Middleware Controls

Context Tracking and Middleware Helpers

The SSG middleware module exposes runtime helpers that inspect or modify generation behavior depending on execution context. The experimental isSSGContext function checks whether c.env[SSG_CONTEXT] evaluates to a truthy value, identifying when a request runs within a static generation build rather than a live server. Two supplementary middleware factories, disableSSG and onlySSG, leverage this environment flag to control route inclusion: disableSSG assigns the header x-hono-disable-ssg (X_HONO_DISABLE_SSG_HEADER_KEY) and returns a 404 via c.notFound(), whereas onlySSG restricts execution exclusively to SSG contexts, returning 404 for live requests. Sources: src/helper/ssg/middleware.ts:5-6, src/helper/ssg/middleware.ts:56-83

Sources: src/helper/ssg/middleware.ts:5-6, src/helper/ssg/middleware.ts:56-83

SSG Parameter Registration

Dynamic routes register their concrete parameter combinations through the ssgParams middleware. This function accepts either a static SSGParams array or a generator function (c: Context) => SSGParams | Promise<SSGParams>. When encountered on a dynamic route path verified by isDynamicRoute, ssgParams evaluates the parameter definitions, attaches them to c.req.raw.ssgParams (cast as AddedSSGDataRequest), and immediately aborts subsequent handler execution by returning c.notFound(). Sources: src/helper/ssg/middleware.ts:36-49

File Resolution and Output Writing

Path Calculation and Extension Mapping

Copyexport const saveContentToFile = async (
  data: Promise<{ routePath: string; content: string | ArrayBuffer; mimeType: string } | undefined>,
  fsModule: FileSystemModule,
  outDir: string,
  extensionMap?: Record<string, string>
): Promise<string | undefined> => {
  const awaitedData = await data
  if (!awaitedData) {
    return
  }
  const { routePath, content, mimeType } = awaitedData
  const filePath = generateFilePath(routePath, outDir, mimeType, extensionMap)
  const dirPath = dirname(filePath)
 
  if (!createdDirs.has(dirPath)) {
    await fsModule.mkdir(dirPath, { recursive: true })
    createdDirs.add(dirPath)
  }
  if (typeof content === 'string') {
    await fsModule.writeFile(filePath, content)
  } else if (content instanceof ArrayBuffer) {
    await fsModule.writeFile(filePath, new Uint8Array(content))
  }
  return filePath
}

Sources: src/helper/ssg/ssg.ts:310-334

Directory Traversal Safeguards

Copyexport const ensureWithinOutDir = (outDir: string, filePath: string): void => {
  const normalizedOutDir = joinPaths('/', outDir)
  const normalizedFilePath = joinPaths('/', filePath)
 
  if (
    normalizedFilePath !== normalizedOutDir &&
    !normalizedFilePath.startsWith(`${normalizedOutDir}/`)
  ) {
    throw new Error(`Path traversal detected: "${filePath}" is outside the output directory`)
  }
}

Sources: src/helper/ssg/utils.ts:77-87

Lifecycle Hooks and Redirect Plugins

Hook Interception Points

The static site generation pipeline exposes multiple hook interception points across route execution to inspect or transform requests and responses. Before a route request is evaluated, beforeRequestHook intercepts the incoming Request object (AddedSSGDataRequest), allowing modifications or cancellation by returning a falsy value. Similarly, afterResponseHook evaluates generated Response instances. If a response carries the header defined by X_HONO_DISABLE_SSG_HEADER_KEY, generation for that route is skipped. Sources: src/helper/ssg/ssg.ts:185-194, src/helper/ssg/ssg.ts:234-281

Client-Side Redirect HTML Synthesis

Copyconst REDIRECT_STATUS_CODES = new Set([301, 302, 303, 307, 308])
 
const generateRedirectHtml = (location: string) => {
  // prettier-ignore
  const content = html`<!DOCTYPE html>
<title>Redirecting to: ${location}</title>
<meta http-equiv="refresh" content="0;url=${location}" />
<meta name="robots" content="noindex" />
<link rel="canonical" href="${location}" />
<body>
<a href="${location}">Redirecting to <code>${location}</code></a>
</body>
`
  return content.toString().replace(/\n/g, '')
}

Sources: src/helper/ssg/plugins.ts:22-36

The redirectPlugin catches specific HTTP redirect status codes and transforms them into self-contained HTML redirection pages suitable for static hosting environments where server-side headers are absent.

Sources: src/helper/ssg/plugins.ts:22-72

Related

• Static File Serving
• JSX Runtime