Orientation Arc
Routing Algorithms
Rendering and JSX
Runtime Adapters
Middleware Ecosystem
Developer Helpers
System Utilities
The following files were used as context for generating this wiki page:
Static Generation (SSG) in Hono enables pre-rendering routes into static files during the build process, significantly improving performance by serving assets directly from the file system rather than invoking the application logic at runtime. This subsystem is designed to crawl the application's defined routes, execute them, and persist their outputs to a specified directory.
By abstracting the file system interface through FileSystemModule, Hono's SSG mechanism remains environment-agnostic, allowing seamless integration with different runtimes like Node.js, Deno, or Bun. This flexibility ensures that the SSG workflow is consistent across various platforms while leveraging environment-specific optimized file writing routines.
The architecture emphasizes composability and extensibility via plugin support. This allows developers to intercept the request lifecycle, handle dynamic routing parameters, or modify generated responses to suit specific requirements, such as handling redirects or content transformations.
The SSG process coordinates route discovery, execution, and persistence. It starts by filtering routes to identify eligible static content, then proceeds through the SSG plugins to collect content and save it to the disk.
The system requires an implementation of FileSystemModule to perform I/O operations. This decoupling allows the core logic to avoid runtime-specific dependencies, ensuring the same toSSG function works across diverse environments.
export interface FileSystemModule {
writeFile(path: string, data: string | Uint8Array): Promise<void>
mkdir(path: string, options: { recursive: boolean }): Promise<void | string>
}Implementations are provided for specific adapters:
src/adapter/bun/ssg.ts.src/adapter/deno/ssg.ts.For routes containing dynamic parameters, Hono uses the ssgParams middleware to inform the generator which specific paths to pre-render. When the generator encounters a route identified by isDynamicRoute, it expects the application to provide context via ssgParams.
Important
The ssgParams middleware effectively "short-circuits" the request processing for those routes in the generator's context, preventing unnecessary handler execution while collecting the required parameters for static rendering.
export const ssgParams: SSGParamsMiddleware = (params) => async (c, next) => {
if (isDynamicRoute(c.req.path)) {
(c.req.raw as AddedSSGDataRequest).ssgParams = Array.isArray(params) ? params : await params(c)
return c.notFound()
}
await next()
}Plugins allow customization of the SSG process. By bundling hooks, plugins can easily inject logic before a request is sent, after a response is received, or after the generation process completes.
The generateFilePath function transforms route paths into valid file system paths, applying directory and extension logic. It guarantees that generated files are contained within the outDir to prevent potential path traversal vulnerabilities.
Caution
The ensureWithinOutDir check is a security invariant that throws an error if a computed filePath escapes the outDir. This is critical for preventing arbitrary file system writes during the generation phase.
toSSGThe toSSG orchestrator follows this sequence:
plugins array.ssgParams.saveContentToFile creates the necessary directories recursively and writes the data to the outputDir using the injected fsModule.afterGenerateHook callbacks after the main operations conclude.Sources: src/helper/ssg/ssg.ts:368-470