快速开始

本文档将引导你完成 Tanplate 的本地设置。远程 Cloudflare 资源和生产 secret 不属于快速开始流程。

前提条件

• 当前稳定版 Node.js
• pnpm 10.33.0
• Git

可以先检查本机版本：

node --version
pnpm --version
git --version

仓库不提供 .nvmrc、engines.node 或 engine-strict，CLI 也不检查 Node 版本；安装直接使用当前 Node。packageManager 仍固定 pnpm 版本。Cloudflare 账号只在准备远程资源或部署时需要。

创建项目

@tanplate/cli 发布后可在目标父目录执行：

pnpm dlx @tanplate/cli create my-app
cd my-app

CLI 会检查 pnpm/Git、克隆模板、安装依赖并运行 init:template / check:template。中断后使用同一项目名加 --resume，详见 初始化 CLI。

初始化当前仓库

已经取得源码时，在仓库根目录执行：

pnpm install
pnpm init:template -- --project my-app

初始化脚本会校验 project.manifest.json，生成三个应用共用的类型化公共配置快照，统一根包名、Worker 名和启用能力所需的本地资源。Authentication 开启时才管理 Auth 变量，Admin 部署时才生成共享 secret/白名单；已有 .dev.vars 自定义项和未知 Wrangler 配置会保留。脚本不会创建远程资源。

准备本地数据

只执行当前 Capability Profile 需要的命令：

pnpm data:migrate:local # 当前 Profile 需要 D1 时
pnpm data:seed:local    # 当前 Profile 部署 Admin 时

Profile 需要 D1 时，本地状态位于 apps/web/.wrangler/state。Admin 部署时通过 Cloudflare Vite Plugin 的 persistState 读取同一份状态，因此 Web 注册的用户可以在 Admin 中管理；纯 Landing 不需要 D1。

data:seed:local 只初始化默认本地超级管理员，不写 Project 或 R2 业务数据。管理员账号和密码都是 admin@6owen.com；bootstrap 可重复执行，已存在时会保持单一 credential，并把账号恢复为已验证的最高权限状态。远程 D1 仍要求显式传入凭据，不会自动采用本地默认值。

启动开发服务器

pnpm dev:web
pnpm dev:admin
pnpm dev:docs

三个命令分别启动独立 Worker。只开发某个应用时无需同时运行另外两个。

提交前验证

pnpm verify

verify 依次执行 format check、lint、全部 workspace 类型检查与测试，以及三个应用的生产 build。涉及真实认证流程时，再运行：

pnpm test:e2e:web
pnpm test:e2e:admin

运行 pnpm test:profiles 可额外验证 Landing、Auth-only、Projects-readonly 和 Auth+Admin 的构建裁剪。

Web E2E 自动迁移 tanplate-web-e2e 专用本地 D1，并在独立 4184 Worker 上验证完整 Session lifecycle；Admin E2E 继续复用开发本地 D1 与默认管理员。CI 在同一个 browser job 中安装一次 Chrome 后依次执行二者。

文档开发

MDX 文件位于 apps/docs/content/docs。新增页面后同步更新该目录的 meta.json 和 .folder.md，然后运行：

pnpm --filter docs generate
pnpm --filter docs typecheck

下一步