Foldkit

Foldkit ↗ 支持单页应用（SPA）、静态站点生成（SSG）和服务端渲染（SSR）。每种模式都使用 Workers Assets 提供浏览器文件。SSR 还会运行 Worker 的 fetch handler。

你需要 Node.js 22.22.2 或更高版本以及 Cloudflare 账户。

创建 Foldkit 应用

使用 create-foldkit-app ↗ 创建项目：
npx create-foldkit-app@latest --name my-foldkit-app
yarn dlx create-foldkit-app@latest --name my-foldkit-app
pnpx create-foldkit-app@latest --name my-foldkit-app
在提示时选择渲染模式。对于 SPA，选择 routing 示例。将包管理器选为 npm。
在项目目录中安装 Wrangler：
```
cd my-foldkit-app
```
npm i -D wrangler
yarn add -D wrangler
pnpm add -D wrangler
bun add -d wrangler

配置渲染模式

在项目目录中创建 wrangler.jsonc 文件，并填入对应渲染模式的配置。

SPA

SPA 构建会将 index.html 和浏览器资源写入 dist。当客户端路由未匹配到资源时，single-page-application 设置会提供 index.html。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-foldkit-app",
  // Set this to today's date
  "compatibility_date": "2026-11-14",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "single-page-application"
  }
}

name = "my-foldkit-app"
# Set this to today's date
compatibility_date = "2026-11-14"

[assets]
directory = "./dist"
not_found_handling = "single-page-application"

SSG

SSG 构建会使用 server bundle 预渲染路由，然后将 HTML 和浏览器资源写入 dist/client。仅使用 Workers Assets 部署 dist/client。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-foldkit-app",
  // Set this to today's date
  "compatibility_date": "2026-11-14",
  "assets": {
    "directory": "./dist/client"
  }
}

name = "my-foldkit-app"
# Set this to today's date
compatibility_date = "2026-11-14"

[assets]
directory = "./dist/client"

SSR

SSR 构建会将 Web fetch handler 写入 dist/server/fetch.js，将浏览器资源写入 dist/client。Worker 处理页面请求，Workers Assets 提供浏览器文件。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-foldkit-app",
  "main": "./dist/server/fetch.js",
  // Set this to today's date
  "compatibility_date": "2026-11-14",
  "assets": {
    "directory": "./dist/client"
  }
}

name = "my-foldkit-app"
main = "./dist/server/fetch.js"
# Set this to today's date
compatibility_date = "2026-11-14"

[assets]
directory = "./dist/client"

预览与部署

构建应用：
npm run build
yarn run build
pnpm run build
在 Workers 运行时中预览：
npx wrangler dev
yarn wrangler dev
pnpm wrangler dev
打开 Wrangler 打印的本地 URL。对于 SPA，打开 /people 并重新加载。对于 SSG，访问 /about/。对于 SSR，增加计数器并重新加载。其基于 cookie 的值应会持久化。
构建并部署应用：
npm run build
yarn run build
pnpm run build
npx wrangler deploy
yarn wrangler deploy
pnpm wrangler deploy

打开 Wrangler 打印的 workers.dev URL 以验证已部署的应用。有关 SSG 和 SSR 构建的更多信息，请参阅 Foldkit 的服务端渲染指南 ↗。