Bootstrap

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.

Preflight

1. Confirm Vercel CLI is installed and authenticated.

vercel --version
vercel whoami

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

vercel teams ls
vercel projects ls --scope 
vercel link --yes --scope  --project 

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

cp .env.example .env.local

Resource Setup: Postgres

Preferred path (Vercel-managed Neon)

1. Read integration setup guidance:

vercel integration guide neon

1. Add Neon integration to the Vercel scope:

vercel integration add neon --scope 

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

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

Env Verification

Compare required keys from 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 \
  /
- **Resource Path**: vercel-integration-neon | dashboard-neon | neon-cli
- **Env Keys**:  required,  present,  missing
- **Secrets**: AUTH_SECRET set in Vercel (value never shown)
- **Migration Status**: not-run | success | failed ()
- **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.

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.

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: build-with-dhiraj
• Source: build-with-dhiraj/ai-workflow-framework-portability-kit
• License: MIT

Install and usage instructions live in the source repository linked above.