SSG 助手

¥SSG Helper

SSG Helper 从你的 Hono 应用生成静态站点。它将检索已注册路由的内容并将其保存为静态文件。

¥SSG Helper generates a static site from your Hono application. It will retrieve the contents of registered routes and save them as static files.

用法

¥Usage

手动

¥Manual

如果你有一个简单的 Hono 应用，如下所示：

¥If you have a simple Hono application like the following:

tsx

// index.tsx
const app = new Hono()

app.get('/', (c) => c.html('Hello, World!'))
app.use('/about', async (c, next) => {
  c.setRenderer((content, head) => {
    return c.html(
      <html>
        <head>
          <title>{head.title ?? ''}</title>
        </head>
        <body>
          <p>{content}</p>
        </body>
      </html>
    )
  })
  await next()
})
app.get('/about', (c) => {
  return c.render('Hello!', { title: 'Hono SSG Page' })
})

export default app

对于 Node.js，创建如下构建脚本：

¥For Node.js, create a build script like this:

// build.ts
import app from './index'
import { toSSG } from 'hono/ssg'
import fs from 'fs/promises'

toSSG(app, fs)

通过执行脚本，文件将输出如下：

¥By executing the script, the files will be output as follows:

bash

ls ./static
about.html  index.html

Vite 插件

¥Vite Plugin

使用 @hono/vite-ssg Vite 插件，你可以轻松处理该过程。

¥Using the @hono/vite-ssg Vite Plugin, you can easily handle the process.

有关更多详细信息，请参见此处：

¥For more details, see here:

https://github.com/honojs/vite-plugins/tree/main/packages/ssg

toSSG

toSSG 是生成静态站点的主要函数，以应用和文件系统模块作为参数。它基于以下内容：

¥toSSG is the main function for generating static sites, taking an application and a filesystem module as arguments. It is based on the following:

输入

¥Input

toSSG 的参数在 ToSSGInterface 中指定。

¥The arguments for toSSG are specified in ToSSGInterface.

export interface ToSSGInterface {
  (
    app: Hono,
    fsModule: FileSystemModule,
    options?: ToSSGOptions
  ): Promise<ToSSGResult>
}

app 指定已注册路由的 new Hono()。
¥app specifies new Hono() with registered routes.
fs 指定以下对象，假设 node:fs/promise。
¥fs specifies the following object, assuming node:fs/promise.

export interface FileSystemModule {
  writeFile(path: string, data: string | Uint8Array): Promise<void>
  mkdir(
    path: string,
    options: { recursive: boolean }
  ): Promise<void | string>
}

使用 Deno 和 Bun 的适配器

¥Using adapters for Deno and Bun

如果要在 Deno 或 Bun 上使用 SSG，则每个文件系统都提供了一个 toSSG 函数。

¥If you want to use SSG on Deno or Bun, a toSSG function is provided for each file system.

对于 Deno：

¥For Deno:

import { toSSG } from 'hono/deno'

toSSG(app) // The second argument is an option typed `ToSSGOptions`.

对于 Bun：

¥For Bun:

import { toSSG } from 'hono/bun'

toSSG(app) // The second argument is an option typed `ToSSGOptions`.

选项

¥Options

选项在 ToSSGOptions 接口中指定。

¥Options are specified in the ToSSGOptions interface.

export interface ToSSGOptions {
  dir?: string
  concurrency?: number
  extensionMap?: Record<string, string>
  plugins?: SSGPlugin[]
}

dir 是静态文件的输出目标。默认值为 ./static。
¥dir is the output destination for Static files. The default value is ./static.
concurrency 是同时生成的文件数。默认值为 2。
¥concurrency is the concurrent number of files to be generated at the same time. The default value is 2.
extensionMap 是一个映射，其中包含 Content-Type 作为键和扩展字符串作为值。这用于确定输出文件的文件扩展名。
¥extensionMap is a map containing the Content-Type as a key and the string of the extension as a value. This is used to determine the file extension of the output file.
plugins 是一个 SSG 插件数组，用于扩展静态站点生成过程的功能。
¥plugins is an array of SSG plugins that extend the functionality of the static site generation process.

输出

¥Output

toSSG 以以下 Result 类型返回结果。

¥toSSG returns the result in the following Result type.

export interface ToSSGResult {
  success: boolean
  files: string[]
  error?: Error
}

生成文件

¥Generate File

路由和文件名

¥Route and Filename

以下规则适用于注册的路由信息和生成的文件名。默认 ./static 的行为如下：

¥The following rules apply to the registered route information and the generated file name. The default ./static behaves as follows:

/ -> ./static/index.html
/path -> ./static/path.html
/path/ -> ./static/path/index.html

文件扩展名

¥File Extension

文件扩展名取决于每个路由返回的 Content-Type。例如，来自 c.html 的响应保存为 .html。

¥The file extension depends on the Content-Type returned by each route. For example, responses from c.html are saved as .html.

如果你想要自定义文件扩展名，请设置 extensionMap 选项。

¥If you want to customize the file extensions, set the extensionMap option.

import { toSSG, defaultExtensionMap } from 'hono/ssg'

// Save `application/x-html` content with `.html`
toSSG(app, fs, {
  extensionMap: {
    'application/x-html': 'html',
    ...defaultExtensionMap,
  },
})

请注意，无论扩展名是什么，以斜杠结尾的路径都会保存为 index.ext。

¥Note that paths ending with a slash are saved as index.ext regardless of the extension.

// save to ./static/html/index.html
app.get('/html/', (c) => c.html('html'))

// save to ./static/text/index.txt
app.get('/text/', (c) => c.text('text'))

中间件

¥Middleware

引入支持 SSG 的内置中间件。

¥Introducing built-in middleware that supports SSG.

ssgParams

你可以使用 Next.js 的 generateStaticParams 之类的 API。

¥You can use an API like generateStaticParams of Next.js.

示例：

¥Example:

app.get(
  '/shops/:id',
  ssgParams(async () => {
    const shops = await getShops()
    return shops.map((shop) => ({ id: shop.id }))
  }),
  async (c) => {
    const shop = await getShop(c.req.param('id'))
    if (!shop) {
      return c.notFound()
    }
    return c.render(
      <div>
        <h1>{shop.name}</h1>
      </div>
    )
  }
)

disableSSG

具有 disableSSG 中间件集的路由被 toSSG 排除在静态文件生成之外。

¥Routes with the disableSSG middleware set are excluded from static file generation by toSSG.

app.get('/api', disableSSG(), (c) => c.text('an-api'))

onlySSG

具有 onlySSG 中间件集的路由将在 toSSG 执行后被 c.notFound() 覆盖。

¥Routes with the onlySSG middleware set will be overridden by c.notFound() after toSSG execution.

app.get('/static-page', onlySSG(), (c) => c.html(<h1>Welcome to my site</h1>))

插件

¥Plugins

插件允许你扩展静态站点生成过程的功能。它们使用钩子在不同阶段自定义生成过程。

¥Plugins allow you to extend the functionality of the static site generation process. They use hooks to customize the generation process at different stages.

钩子类型

¥Hook Types

插件可以使用以下钩子来自定义 toSSG 流程：

¥Plugins can use the following hooks to customize the toSSG process:

export type BeforeRequestHook = (req: Request) => Request | false
export type AfterResponseHook = (res: Response) => Response | false
export type AfterGenerateHook = (
  result: ToSSGResult
) => void | Promise<void>

BeforeRequestHook：处理每个请求前调用。返回 false 可跳过路由。
¥BeforeRequestHook: Called before processing each request. Return false to skip the route.
AfterResponseHook:收到每个响应后调用。返回 false 可跳过文件生成。
¥AfterResponseHook: Called after receiving each response. Return false to skip file generation.
AfterGenerateHook:整个生成过程完成后调用。
¥AfterGenerateHook: Called after the entire generation process completes.

插件界面

¥Plugin Interface

export interface SSGPlugin {
  beforeRequestHook?: BeforeRequestHook | BeforeRequestHook[]
  afterResponseHook?: AfterResponseHook | AfterResponseHook[]
  afterGenerateHook?: AfterGenerateHook | AfterGenerateHook[]
}

基本插件示例

¥Basic Plugin Examples

仅过滤 GET 请求：

¥Filter only GET requests:

const getOnlyPlugin: SSGPlugin = {
  beforeRequestHook: (req) => {
    if (req.method === 'GET') {
      return req
    }
    return false
  }
}

按状态码过滤：

¥Filter by status code:

const statusFilterPlugin: SSGPlugin = {
  afterResponseHook: (res) => {
    if (res.status === 200 || res.status === 500) {
      return res
    }
    return false
  }
}

日志生成的文件：

¥Log generated files:

const logFilesPlugin: SSGPlugin = {
  afterGenerateHook: (result) => {
    if (result.files) {
      result.files.forEach((file) => console.log(file))
    }
  }
}

高级插件示例

¥Advanced Plugin Example

以下是创建生成 sitemap.xml 文件的站点地图插件的示例：

¥Here's an example of creating a sitemap plugin that generates a sitemap.xml file:

// plugins.ts
import fs from 'node:fs/promises'
import path from 'node:path'
import type { SSGPlugin } from 'hono/ssg'
import { DEFAULT_OUTPUT_DIR } from 'hono/ssg'

export const sitemapPlugin = (baseURL: string): SSGPlugin => {
  return {
    afterGenerateHook: (result, fsModule, options) => {
      const outputDir = options?.dir ?? DEFAULT_OUTPUT_DIR
      const filePath = path.join(outputDir, 'sitemap.xml')
      const urls = result.files.map((file) =>
        new URL(file, baseURL).toString()
      )
      const siteMapText = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${urls.map((url) => `<url><loc>${url}</loc></url>`).join('\n')}
</urlset>`
      fsModule.writeFile(filePath, siteMapText)
    },
  }
}

应用插件：

¥Applying plugins:

import app from './index'
import { toSSG } from 'hono/ssg'
import { sitemapPlugin } from './plugins'

toSSG(app, fs, {
  plugins: [
    getOnlyPlugin,
    statusFilterPlugin,
    logFilesPlugin,
    sitemapPlugin('https://example.com')
  ],
})

SSG 助手 ​

用法 ​

手动 ​

Vite 插件 ​

toSSG ​

输入 ​

使用 Deno 和 Bun 的适配器 ​

选项 ​

输出 ​

生成文件 ​

路由和文件名 ​

文件扩展名 ​

中间件 ​

ssgParams ​

disableSSG ​

onlySSG ​

插件 ​

钩子类型 ​

插件界面 ​

基本插件示例 ​

高级插件示例 ​