Dev Environment Setup

Goal: clone → install → build → run in under 15 minutes. If it takes longer, the setup is broken.

Step 1: Check Prerequisites

Detect the project type from the repo and verify:

Check	How
Runtime version	.node-version, .python-version, .tool-versions, rust-toolchain.toml, build.gradle.kts
Package manager	package-lock.json (npm), yarn.lock (yarn), pnpm-lock.yaml (pnpm), Pipfile.lock, poetry.lock, Cargo.lock, go.sum
Required services	docker-compose.yml, README setup section
Environment vars	.env.example, .env.template

Step 2: Install Dependencies

# Detect and run the appropriate install command
# npm install / yarn / pnpm install / pip install / cargo build / go mod download

Step 3: Configure Environment

1. Copy .env.example to .env (if exists)
2. Fill in required values (API keys, DB connection strings)
3. Start required services (docker compose up -d if applicable)

Step 4: Verify Build

# Run the project's build command
# Run the project's test suite

Step 5: Verify Dev Server

# Start the dev server and confirm it responds

Git Configuration

git config pull.rebase true          # Clean history
git config push.autoSetupRemote true # Auto-track branches

Common Troubleshooting

Problem	Likely Cause	Fix
"Module not found"	Missing dependencies	Re-run install command
Version mismatch	Wrong runtime version	Check version file, use version manager (nvm, pyenv, rustup)
Build fails	Missing system dependency	Check README, install OS-level packages
Port in use	Another process	lsof -i :PORT to find and stop it
Permission denied	File permissions	Check file ownership, avoid sudo for package installs
Tests fail on fresh clone	Missing env vars or services	Check .env.example and docker-compose.yml