create-instant-app 使用指南：用一条命令快速搭建 InstantDB 应用脚手架

• 后端
• 数据库

create-instant-app是 Instant 开源仓库中负责应用脚手架初始化的 CLI 工具，它让你只需执行npx create-instant-app，即可在交互式提示或命令行参数驱动下，生成接入 InstantDB（auth、权限、存储、presence、streams 等能力）的前后端项目骨架。读完本文，你将掌握该工具的全部用法（交互式流程、常用参数、非交互式一键搭建）、其脚手架实现原理（本地模板 / tiged 拉取、规则文件注入、包管理器探测），以及如何在本地开发和调试这个 CLI 本身。

快速开始：一条命令拉起 Instant 应用

create-instant-app的使用方式与众多create-*脚手架一致：无需预先安装任何全局依赖，直接通过npx调用即可（源码中通过package.json的bin字段暴露了create-instant-app命令，见 package.json）。

npx create-instant-app

运行后工具会依次向你提问：

1. 项目/文件夹名称：默认值为awesome-todos，输入的名称会同时作为目录名与应用名（cli.ts 中通过validateAppName校验，仅允许小写字母、数字、-与_，也支持.表示使用当前目录）。
2. 选择框架模板：默认Web: Next.js，可切换为Mobile: Expo，或展开次级选项选择 Vite React、Vite Vanilla TS、Tanstack Start、Bun + React、SolidJS、SvelteKit、Vite Vue、Vercel AI SDK 等更多模板。
3. 为哪种 AI 工具生成规则文件：可选 Claude、Cursor、Codex、Gemini、Zed、Windsurf 或 None，默认 Claude。
4. 连接/创建 InstantDB 应用：若未登录，可选择登录账户、创建临时应用（有效期两周）或稍后创建。

完成这些步骤后，工具会自动拉取模板、安装依赖（自动探测 npm/pnpm/yarn/bun）、初始化 git 仓库（默认开启），并把生成的APP_ID/ admin token 写入.env文件，随后打印下一步命令（通常是cd <dir>然后pnpm run dev之类），整个项目即可运行。

常用命令行参数速查

除了纯交互模式，CLI 还提供了大量参数用于跳过提问、指定模板和连接已有应用。以下参数均定义于 cli.ts，命令版本号直接复用@instantdb/version包（--version输出）。

几个典型的非交互式用法示例：

# 使用默认 Next.js 模板、默认配置，全自动创建 npx create-instant-app my-app --yes # 指定 Vite + React 模板并注入 Cursor 规则文件 npx create-instant-app my-app --vite-react --cursor # 关联已有应用（未登录时提供 token） npx create-instant-app my-app --app <app-id> --token <admin-token>

在--yes模式下，工具会自动决定创建方式：如果检测到已登录则创建真实应用，否则创建一个临时（ephemeral）应用（见 login.ts 中tryConnectApp的分支逻辑）。临时应用有效期约两周，之后可用npx instant-cli claim认领为正式应用。

可用模板与对应环境变量

create-instant-app内置的模板清单定义在 projectBase.ts，共 13 种：

• Web 框架类：next-js-app-dir、vite-react、vite-vanilla、tanstack-start、tanstack-start-with-tanstack-query、sveltekit、vue-vite、solidjs-vite
• Mobile 类：expo
• AI 应用类：vercel-ai-sdk、ai-chat
• 其他：bun-react、python-script

每种模板都声明了自己的APP_ID环境变量名，脚手架完成应用关联后会据此把凭据写入对应环境的.env文件：

此外，projectBase.ts还定义了每个模板的后端配置文件（backend config）：普通前端模板只有一个客户端init配置（src/lib/db.ts，启用 websocket），而tanstack-start、vercel-ai-sdk、ai-chat等模板还额外包含一个 admin 配置（src/lib/adminDb.ts，初始化为init或initAdmin，不启用 websocket），用于服务端管理操作。python-script模板则对应main.py中的 Python 后端配置。

脚手架生成流程与底层原理

了解完用法后，再来看它内部究竟做了什么。入口是 index.ts，整个流程如下：

1. 解析参数与提问：runCli()（cli.ts）用commander解析参数，用@clack/prompts渲染交互式提问；支持INSTANT_CLI_API_URI/INSTANT_CLI_DASH_URI环境变量覆盖后端地址（backendConfig.ts）。

2. 拉取模板代码：scaffoldBase()（scaffold.ts）按优先级选择三种方式：

   • dev：设置了INSTANT_CLI_DEV与INSTANT_REPO_FOLDER时，直接从本地仓库的examples/<template>目录复制（遵循.gitignore规则，见copyRespectingGitignore）；
   • bundled-template：若包内template/base/<template>目录存在则直接复制（生产发布时模板随 npm 包分发，同时会把_gitignore改回.gitignore）；
   • tiged：以上都不满足时，用 tiged（degit 的维护分支）以 tar 模式从instantdb/instant/examples/<template>拉取对应示例子目录。

   脚手架还会处理目录冲突（空目录继续、非空目录询问"中止或清空"）、删除多余的锁文件、为 Expo 追加.npmrc（node-linker=hoisted），并把app.json与app/_layout.tsx中的模板占位名替换为你的应用名。

3. 注入 AI 规则文件：addRuleFiles()（ruleFiles.ts）将 template/rules/AGENTS.md 复制到项目根目录，文件名按所选 AI 工具映射：Claude →CLAUDE.md，Gemini →GEMINI.md，Cursor / Codex / Zed / Windsurf →AGENTS.md。

4. 连接或创建应用：tryConnectApp()（login.ts）根据登录状态与参数执行三种策略之一：创建真实应用（create，POST/dash/apps）、导入已有应用（import，通过--app/--token或登录态校验访问权限）、创建临时应用（ephemeral，POST/dash/apps/ephemeral，附带一套默认宽松的 permissions 规则）。未登录时会弹出选择菜单，选择登录则通过/dash/cli/auth/register获取 ticket 并打开浏览器完成授权，轮询/dash/cli/auth/check等待结果（最长约 120 秒）。

5. 写凭据、装依赖、初始化 git：把appId/adminToken写入.env（applyEnvFile）；Python 模板改写pyproject.toml的name字段，其余模板更新package.json的name与packageManager字段；随后自动执行包管理器安装（installPackages.ts），并在默认开启时git init。

6. 输出启动指引：按模板类型打印下一步命令；若使用了--ai，还会调用 Claude Code 基于你的提示词在项目内继续生成应用逻辑（claude.ts）。

值得注意的是包管理器自动探测逻辑（getUserPkgManager.ts）：通过读取npm_config_user_agent环境变量判断你调用npx时使用的是 yarn、pnpm 还是 bun，否则回退到 npm；唯一例外是bun-react模板强制使用 bun。这意味着无论你惯用哪种工具链，脚手架都会用同一套包管理器完成安装。

应用名校验规则

应用名需要同时满足 npm 包名规范，校验逻辑在 validateAppName.ts：

/^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/

即：名称只能包含小写字母、数字、-、_与.，可选支持 npm scope 前缀（@org/name形式）。parseNameAndPath会从输入中拆分出 scoped 应用名与目录路径，例如@acme/todo-app会被解析为应用名@acme/todo-app、目录todo-app；传入.时则使用当前目录名作为应用名。无效名称会直接报错退出，交互模式下则提示重新输入。

本地开发与调试这个 CLI

如果你想基于当前仓库修改或调试create-instant-app本身，仓库提供了完整的开发工作流（见 package.json）：

# 安装依赖（在仓库根目录执行 pnpm install 后） pnpm run build # 构建：tsup 打包，构建前会自动执行 copy-examples pnpm run dev # 开发模式：tsup --watch 监听重建

构建产物为dist/index.js（package.json的exports与bin均指向它）。开发时可通过pnpm link --global把当前包软链接到全局，之后即可在任何目录直接使用create-instant-app命令（等价于npx create-instant-app的本地版）：

pnpm link --global create-instant-app # 任意目录下直接使用

调试完成后解除链接：

pnpm uninstall create-instant-app --global

本地开发时若希望跳过从 GitHub 拉取模板（加快迭代、便于离线），可以设置INSTANT_CLI_DEV与INSTANT_REPO_FOLDER指向仓库的 examples 目录，脚手架便会直接从本地examples/<template>复制代码；若只设置了INSTANT_CLI_DEV而未设置INSTANT_REPO_FOLDER，工具会打印警告并回退到从远程拉取。

仓库还提供了单元测试与端到端测试保障（pnpm test、pnpm test:e2e），其中 create-instant-app.e2e.test.ts 覆盖了从执行 CLI 到项目生成的完整链路，是理解各参数实际行为的最佳参考。

小结

create-instant-app的价值在于把"选模板 → 拉代码 → 配环境变量 → 关联/创建 InstantDB 应用 → 装依赖 → 初始化 git"这一整套初始化动作收敛为一条命令：日常使用只需npx create-instant-app跟随引导即可；CI 或脚本化场景可使用--yes等参数全自动生成；需要接入已有数据时用--app/--token关联；而--ai模式则把脚手架与 Claude Code 结合，实现"一句话生成 InstantDB 应用"。配合本文对 cli.ts、scaffold.ts、login.ts 等核心源码的拆解，你既可以熟练使用它，也可以在需要时对它进行本地开发和二次定制。

• 后端
• 数据库