setup-env

name	setup-env
description	Bootstrap a complete development environment for new contributors. Installs dependencies, configures tools, seeds databases, and verifies everything works.

Setup Dev Environment

Automate the full development environment setup for new contributors. This skill handles dependency installation, tool configuration, database setup, and verification — reducing "works on my machine" issues.

When to Use

Use this skill when:

• A new developer is joining the project
• Setting up the project on a new machine
• Resetting a broken local environment
• Verifying the setup docs are accurate

Instructions

1. Read the project template at ../../_references/project-template.md for the expected project structure and tooling.

2. Check system prerequisites:

   • Node.js version matches .nvmrc or .node-version or engines in package.json
   • Package manager is correct (npm, pnpm, or yarn — check for lockfiles)
   • Git is installed and configured with name and email
   • Docker is running (if project uses Docker for databases/services)
   • Required CLI tools are installed (check project README for prerequisites)

   If prerequisites are missing, provide install commands:

   # Example for macOS
   brew install node@20 pnpm docker
   nvm use  # if .nvmrc exists
   

3. Install dependencies:

   • Run the correct install command (pnpm install, npm install, yarn)
   • Verify no peer dependency warnings
   • Check that postinstall scripts completed successfully (Prisma generate, Husky, etc.)

4. Configure environment:

   • Copy .env.example to .env if .env doesn't exist
   • Fill in safe development defaults for all variables
   • Flag any variables that require manual setup (API keys, OAuth credentials)
   • Generate required secrets (e.g., openssl rand -hex 32 for JWT secrets)

5. Set up the database (if applicable):

   • Start database container if using Docker:

     docker compose up -d postgres  # or mysql, mongo, etc.
     

   • Wait for database to be ready (health check or connection retry)
   • Run migrations: npx prisma migrate dev or equivalent
   • Seed development data: npx prisma db seed or npm run seed

6. Configure development tools:

   • Set up Git hooks (Husky): npx husky install
   • Verify editor config is picked up (.editorconfig, VS Code settings)
   • Install recommended VS Code extensions if .vscode/extensions.json exists
   • Set up pre-commit hooks (lint-staged, commitlint)

7. Verify the setup: Run each verification step and report results:

   # Type checking
   npx tsc --noEmit
   
   # Linting
   npm run lint
   
   # Tests
   npm test
   
   # Dev server starts
   timeout 10 npm run dev || true
   
   # Build succeeds
   npm run build
   

8. Output a setup report:

   ## Environment Setup Complete
   
   | Step              | Status | Notes                    |
   |-------------------|--------|--------------------------|
   | Prerequisites     | ✅     | Node 20.11, pnpm 8.15   |
   | Dependencies      | ✅     | 847 packages installed   |
   | Environment       | ⚠️     | 2 vars need manual setup |
   | Database          | ✅     | Migrated + seeded        |
   | Dev Tools         | ✅     | Husky, lint-staged       |
   | Verification      | ✅     | Types, lint, tests pass  |
   
   ### Manual Steps Required
   1. Get a Stripe test key from dashboard.stripe.com
   2. Set up OAuth app at github.com/settings/developers
   
   ### Quick Start
   npm run dev → http://localhost:3000
   

Example Usage

Set up this project for local development

I just cloned this repo, help me get it running