bootstrap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Bootstrap Orchestrator

项目启动编排器

Execute bootstrap in strict order. Do not run migrations or development server until project linking and environment verification are complete.

严格按照顺序执行启动流程。在项目关联和环境验证完成前，不要运行迁移命令或开发服务器。

Rules

规则

Do not run
```
db:push
```
,
```
db:migrate
```
,
```
db:seed
```
, or
```
dev
```
until Vercel linking is complete and env keys are verified.
Prefer Vercel-managed provisioning (
```
vercel integration ...
```
) for shared resources.
Use provider CLIs only as fallback when Vercel integration flow is unavailable.
Never echo secret values in terminal output, logs, or summaries.

在Vercel关联完成且环境变量密钥验证通过前，不要运行
```
db:push
```
、
```
db:migrate
```
、
```
db:seed
```
或
```
dev
```
命令。
共享资源优先使用Vercel托管的配置方案（
```
vercel integration ...
```
）。
仅当Vercel集成流程不可用时，才作为备选方案使用供应商CLI。
永远不要在终端输出、日志或摘要中回显敏感值。

Preflight

预检查

Confirm Vercel CLI is installed and authenticated.

bash

vercel --version
vercel whoami

Confirm repo linkage by checking
```
.vercel/project.json
```
.
If not linked, inspect available teams/projects before asking the user to choose:

bash

vercel teams ls
vercel projects ls --scope <team>
vercel link --yes --scope <team> --project <project>

Find the env template in priority order:
```
.env.example
```
,
```
.env.sample
```
,
```
.env.template
```
.
Create local env file if missing:

bash

cp .env.example .env.local

确认Vercel CLI已安装且已完成身份认证。

bash

vercel --version
vercel whoami

检查
```
.vercel/project.json
```
确认仓库关联状态。
如果未关联，先查询可用的团队/项目再让用户选择：

bash

vercel teams ls
vercel projects ls --scope <team>
vercel link --yes --scope <team> --project <project>

按优先级查找环境变量模板：
```
.env.example
```
、
```
.env.sample
```
、
```
.env.template
```
。
如果本地环境文件缺失则创建：

bash

cp .env.example .env.local

Resource Setup: Postgres

资源配置：Postgres

Preferred path (Vercel-managed Neon)

优先方案（Vercel托管的Neon）

Read integration setup guidance:

bash

vercel integration guide neon

Add Neon integration to the Vercel scope:

bash

vercel integration add neon --scope <team>

Verify expected environment variable names exist in Vercel and pull locally:

bash

vercel env ls
vercel env pull .env.local --yes

查看集成设置指南：

bash

vercel integration guide neon

为Vercel作用域添加Neon集成：

bash

vercel integration add neon --scope <team>

验证Vercel中存在预期的环境变量名称并拉取到本地：

bash

vercel env ls
vercel env pull .env.local --yes

Fallback path 1 (Dashboard)

备选方案1（控制台）

Provision Neon through the Vercel dashboard integration UI.
Re-run
```
vercel env pull .env.local --yes
```
.

通过Vercel控制台集成UI配置Neon资源。
重新执行
```
vercel env pull .env.local --yes
```
。

Fallback path 2 (Neon CLI)

备选方案2（Neon CLI）

Use Neon CLI only when Vercel-managed provisioning is unavailable. After creating resources, add required env vars in Vercel and pull again.

仅当Vercel托管配置不可用时使用Neon CLI。创建资源后，在Vercel中添加所需环境变量并再次拉取到本地。

AUTH_SECRET Generation

AUTH_SECRET生成

Generate a high-entropy secret without printing it, then store it in Vercel and refresh local env:

bash

AUTH_SECRET="$(node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))")"
printf "%s" "$AUTH_SECRET" | vercel env add AUTH_SECRET development preview production
unset AUTH_SECRET
vercel env pull .env.local --yes

生成高熵密钥且不打印输出，然后存储到Vercel并刷新本地环境变量：

bash

AUTH_SECRET="$(node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))")"
printf "%s" "$AUTH_SECRET" | vercel env add AUTH_SECRET development preview production
unset AUTH_SECRET
vercel env pull .env.local --yes

Env Verification

环境变量验证

Compare required keys from template file against

.env.local

keys (names only, never values):

bash

template_file=""
for candidate in .env.example .env.sample .env.template; do
  if [ -f "$candidate" ]; then
    template_file="$candidate"
    break
  fi
done

comm -23 \
  <(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' "$template_file" | cut -d '=' -f 1 | sort -u) \
  <(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' .env.local | cut -d '=' -f 1 | sort -u)

Proceed only when missing key list is empty.

对比模板文件中的必填密钥和

.env.local

中的密钥（仅对比名称，绝不对比值）：

bash

template_file=""
for candidate in .env.example .env.sample .env.template; do
  if [ -f "$candidate" ]; then
    template_file="$candidate"
    break
  fi
done

comm -23 \
  <(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' "$template_file" | cut -d '=' -f 1 | sort -u) \
  <(grep -E '^[A-Za-z_][A-Za-z0-9_]*=' .env.local | cut -d '=' -f 1 | sort -u)

仅当缺失密钥列表为空时才可继续后续流程。

App Setup

应用配置

After linkage + env verification:

bash

npm run db:push
npm run db:seed
npm run dev

Use the repository package manager (

npm

pnpm

bun

, or

yarn

) and run only scripts that exist in

package.json

完成关联+环境变量验证后执行：

bash

npm run db:push
npm run db:seed
npm run dev

使用仓库对应的包管理器（

npm

、

pnpm

、

bun

或

yarn

），仅运行

package.json

中存在的脚本。

UI Baseline for Next.js + shadcn Projects

Next.js + shadcn项目的UI基准配置

After linkage and env verification, establish the UI foundation before feature work:

Add a baseline primitive set:

npx shadcn@latest add button card input label textarea select switch tabs dialog alert-dialog sheet dropdown-menu badge separator skeleton table

Apply the Geist font fix in
```
layout.tsx
```
and
```
globals.css
```
.
Confirm the app shell uses
```
bg-background text-foreground
```
.
Default to dark mode for product, admin, and AI apps unless the repo is clearly marketing-first.

完成关联和环境变量验证后，在功能开发前搭建UI基础：

添加基础原组件集：

npx shadcn@latest add button card input label textarea select switch tabs dialog alert-dialog sheet dropdown-menu badge separator skeleton table

在
```
layout.tsx
```
和
```
globals.css
```
中应用Geist字体修复。
确认应用外壳使用
```
bg-background text-foreground
```
样式。
产品类、管理类、AI类应用默认启用深色模式，除非仓库明确是营销优先的项目。

Bootstrap Verification

启动验证

Confirm each checkpoint:

```
vercel whoami
```
succeeds.
```
.vercel/project.json
```
exists and matches chosen project.
Postgres integration path completed (Vercel integration, dashboard, or provider CLI fallback).
```
vercel env pull .env.local --yes
```
succeeds.
Required env key diff is empty.
Database command status is recorded (
```
db:push
```
,
```
db:seed
```
,
```
db:migrate
```
,
```
db:generate
```
as applicable).
```
dev
```
command starts without immediate config/auth/env failure.

If verification fails, stop and report exact failing step plus remediation.

确认每个检查点都通过：

```
vercel whoami
```
执行成功。
```
.vercel/project.json
```
存在且匹配所选项目。
Postgres集成流程已完成（Vercel集成、控制台或供应商CLI备选方案）。
```
vercel env pull .env.local --yes
```
执行成功。
必填环境变量差异为空。
数据库命令状态已记录（对应执行的
```
db:push
```
、
```
db:seed
```
、
```
db:migrate
```
、
```
db:generate
```
）。
```
dev
```
命令启动后没有立即出现配置/认证/环境变量相关故障。

如果验证失败，停止流程并上报具体失败步骤及修复方案。

Summary Format

摘要格式

Return a final bootstrap summary in this format:

undefined

按照以下格式返回最终启动摘要：

undefined

Bootstrap Result

启动结果

Linked Project: <team>/<project>
Resource Path: vercel-integration-neon | dashboard-neon | neon-cli
Env Keys: <count> required, <count> present, <count> missing
Secrets: AUTH_SECRET set in Vercel (value never shown)
Migration Status: not-run | success | failed (<step>)
Dev Result: not-run | started | failed

undefined

关联项目: <team>/<project>
资源配置路径: vercel-integration-neon | dashboard-neon | neon-cli
环境变量: <count> 个必填, <count> 个已存在, <count> 个缺失
密钥: AUTH_SECRET已在Vercel中配置（值永不展示）
迁移状态: not-run | success | failed (<step>)
开发服务结果: not-run | started | failed

undefined

Bootstrap Next Steps

启动后续步骤

If env keys are still missing, add the missing keys in Vercel and re-run
```
vercel env pull .env.local --yes
```
.
If DB commands fail, fix connectivity/schema issues and re-run only the failed db step.
If
```
dev
```
fails, resolve runtime errors, then restart with your package manager's
```
run dev
```
.

如果仍有缺失的环境变量，在Vercel中添加缺失的密钥后重新执行
```
vercel env pull .env.local --yes
```
。
如果数据库命令失败，修复连接/ schema问题后仅重新运行失败的数据库步骤。
如果
```
dev
```
命令失败，解决运行时错误后，使用包管理器的
```
run dev
```
命令重启服务。

next-forge Projects

next-forge项目

If the project was scaffolded with

npx next-forge init

(detected by

pnpm-workspace.yaml

packages/auth

packages/database

@repo/*

imports):

Env files are per-app (

apps/app/.env.local

apps/web/.env.local

apps/api/.env.local

) plus

packages/database/.env

Run

pnpm migrate

(not

db:push

) — it runs

prisma format

prisma generate

prisma db push

Minimum env vars:

DATABASE_URL

CLERK_SECRET_KEY

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

NEXT_PUBLIC_APP_URL

NEXT_PUBLIC_WEB_URL

NEXT_PUBLIC_API_URL

Optional services (Stripe, Resend, PostHog, etc.) can be skipped initially — but remove their
```
@repo/*
```
imports from app
```
env.ts
```
files to avoid validation errors.
Deploy as 3 separate Vercel projects with root directories
```
apps/app
```
,
```
apps/api
```
,
```
apps/web
```
.

=> skill: next-forge — Full next-forge monorepo guide

如果项目是通过

npx next-forge init

搭建的（可通过

pnpm-workspace.yaml

packages/auth

packages/database

@repo/*

导入检测）：

环境变量文件按应用划分（

apps/app/.env.local

、

apps/web/.env.local

、

apps/api/.env.local

）以及

packages/database/.env

。

运行

pnpm migrate

（不要用

db:push

）—— 该命令会执行

prisma format

prisma generate

prisma db push

。

最低要求的环境变量：

DATABASE_URL

、

CLERK_SECRET_KEY

、

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

、

NEXT_PUBLIC_APP_URL

、

NEXT_PUBLIC_WEB_URL

、

NEXT_PUBLIC_API_URL

。

可选服务（Stripe、Resend、PostHog等）初始阶段可以跳过——但需要从应用的
```
env.ts
```
文件中移除对应的
```
@repo/*
```
导入，避免验证错误。
作为3个独立的Vercel项目部署，根目录分别为
```
apps/app
```
、
```
apps/api
```
、
```
apps/web
```
。

=> 技能：next-forge — 完整next-forge monorepo指南