Bootstrap

Project Bootstrap Orchestrator

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

When to Use

Use this skill when:

• Setting up a freshly cloned repository that depends on Vercel-linked resources (Postgres, Auth, Blob, Edge Config, Upstash, etc.).
• Repairing a repo whose environment or database state is broken or incomplete.
• You detect .env.example, .env.sample, .env.template, drizzle.config.*, prisma/schema.prisma, auth.*, or next-forge workspace markers.
• The user asks to "bootstrap", "set up", "link", "pull env", or "get the project running".
• Bash patterns like vercel link, vercel env pull, npm run db:push, or npm run dev appear in instructions.

Prerequisites

• Vercel CLI installed and authenticated (vercel --version, vercel whoami).
• Node.js runtime available for secret generation (node -e).
• Package manager detected from repo lockfiles (package-lock.json → npm, pnpm-workspace.yaml → pnpm, bun.lockb → bun, yarn.lock → yarn).
• Windows host (primary): PowerShell is the default shell. Commands below are POSIX-style for cross-platform Vercel CLI and Node; adapt quoting for PowerShell where noted. The library path on the authoring machine is ~\agent-skills\library\bootstrap\SKILL.md.

Procedure

0. Hard Rules (do not violate)

• Never 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 the Vercel integration flow is unavailable.
• Never echo secret values in terminal output, logs, or summaries. Key names only.
• Never delete .env.local or .vercel/project.json without explicit user confirmation.
• Use the repository's package manager (npm, pnpm, bun, or yarn) and run only scripts that exist in package.json.

1. Preflight — Vercel CLI & Linkage

1. Confirm Vercel CLI is installed and authenticated:

vercel --version
vercel whoami

2. Confirm repo linkage by checking .vercel/project.json:

cat .vercel/project.json

3. If not linked, inspect available teams/projects before asking the user to choose:

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

4. Find the env template in priority order: .env.example, .env.sample, .env.template.

5. Create local env file if missing:

cp .env.example .env.local

PowerShell note: Use Copy-Item .env.example .env.local if cp is not aliased.

2. Resource Setup — Postgres (Neon)

Preferred path (Vercel-managed Neon)

1. Read integration setup guidance:

vercel integration guide neon

2. Add Neon integration to the Vercel scope:

vercel integration add neon --scope <team>

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

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

Fallback path 1 (Dashboard)

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

Fallback path 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 env pull .env.local --yes

3. AUTH_SECRET Generation

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

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

PowerShell note: The above uses POSIX subshell syntax. In PowerShell, generate and pipe differently:

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

4. Env Verification

Compare required keys from the template file against .env.local keys (names only, never values):

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 the missing key list is empty. If keys are missing, add them in Vercel and re-pull.

5. App Setup — Database & Dev

After linkage + env verification:

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

Replace npm with the repo's package manager. Run only scripts that exist in package.json (check db:push, db:seed, db:migrate, db:generate as applicable).

6. UI Baseline for Next.js + shadcn Projects

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

1. 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

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

7. next-forge Projects

If the project was scaffolded with npx next-forge init (detected by pnpm-workspace.yaml + packages/auth + packages/database + @repo/* imports):

1. Env files are per-app (apps/app/.env.local, apps/web/.env.local, apps/api/.env.local) plus packages/database/.env.
2. Run pnpm migrate (not db:push) — it runs prisma format + prisma generate + prisma db push.
3. 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.
4. Optional services (Stripe, Resend, PostHog, etc.) can be skipped initially — but remove their @repo/* imports from app env.ts files to avoid validation errors.
5. Deploy as 3 separate Vercel projects with root directories apps/app, apps/api, apps/web.

Related skill: next-forge — Full next-forge monorepo guide.

Pitfalls

• Running db commands before linking/env verification — violates hard rules; can write to wrong database or fail silently. Always complete steps 1–4 first.
• Echoing secret values — never print AUTH_SECRET or any secret value. Use key names only in summaries and logs.
• Wrong package manager — using npm in a pnpm/bun workspace causes phantom dependencies and lockfile conflicts. Detect from lockfiles.
• next-forge db:push vs pnpm migrate — next-forge repos must use pnpm migrate; running db:push directly skips prisma format and prisma generate.
• Optional service env validation — next-forge env.ts files validate imported @repo/* packages. If you skip Stripe/Resend/PostHog, remove their imports or the app will crash on boot.
• Multiple .env.local files in monorepos — each app needs its own env file; a root .env.local is insufficient.
• Vercel integration not available — fall back to dashboard or provider CLI, but always re-run vercel env pull .env.local --yes after manual provisioning.
• PowerShell quoting — POSIX subshells $(...) and process substitution <(...) do not work in PowerShell; adapt as noted.
• Deleting .vercel/project.json — never delete without explicit user confirmation; it breaks linkage and requires re-linking.

Verification

Confirm each checkpoint before declaring bootstrap complete:

1. Vercel auth: vercel whoami succeeds (prints username).
2. Linkage: .vercel/project.json exists and matches chosen project:

cat .vercel/project.json

3. Postgres integration: one path completed (Vercel integration, dashboard, or provider CLI fallback).
4. Env pull: vercel env pull .env.local --yes succeeds (exit code 0).
5. Required env key diff is empty:

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

Output must be empty.

6. Database commands: status recorded (db:push, db:seed, db:migrate, db:generate as applicable).
7. Dev server: npm run dev (or equivalent) starts without immediate config/auth/env failure.

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

Summary Format

Return a final bootstrap summary in this format:

## 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

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.