dev-environment-bootstrapper

Dev Environment Bootstrapper

Create consistent, reproducible development environments across all machines.

Core Workflow

1. Detect stack: Identify languages and tools used in project
2. Choose version manager: Select appropriate tool (Volta, asdf, mise, nvm, pyenv)
3. Generate configs: Create .tool-versions, .nvmrc, package.json volta fields, etc.
4. Setup environment vars: Create .env.example with all required variables
5. Write setup script: Generate bootstrap script for automated setup
6. Create onboarding doc: Write SETUP.md with step-by-step instructions

Version Management Strategies

Volta (Recommended for Node.js)

// package.json
{
  "volta": {
    "node": "20.11.0",
    "pnpm": "8.15.0"
  }
}

asdf (Multi-language)

# .tool-versions
nodejs 20.11.0
python 3.11.7
ruby 3.2.2

mise (Modern alternative to asdf)

# .mise.toml
[tools]
node = "20.11.0"
python = "3.11"

nvm (Node.js only)

# .nvmrc
20.11.0

Environment Variables Template

# .env.example

# Application
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# External APIs
OPENAI_API_KEY=sk-...
STRIPE_SECRET_KEY=sk_test_...

# Feature Flags
ENABLE_FEATURE_X=false

Setup Script Structure

For Node.js Projects

#!/bin/bash
set -e

echo "🚀 Setting up development environment..."

# Check prerequisites
command -v pnpm >/dev/null 2>&1 || { echo "Installing pnpm..."; npm install -g pnpm; }

# Install dependencies
echo "📦 Installing dependencies..."
pnpm install

# Setup environment
echo "⚙️ Setting up environment variables..."
cp .env.example .env
echo "Edit .env file with your values"

# Setup database (if needed)
if [ -f "prisma/schema.prisma" ]; then
  echo "🗄️ Setting up database..."
  pnpm prisma generate
  pnpm prisma migrate dev
fi

echo "✅ Setup complete! Run 'pnpm dev' to start"

For Python Projects

#!/bin/bash
set -e

echo "🚀 Setting up development environment..."

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Setup environment
cp .env.example .env

# Run migrations
python manage.py migrate

echo "✅ Setup complete! Run 'source venv/bin/activate && python manage.py runserver'"

Onboarding Documentation Template

# Development Setup

## Prerequisites

- Node.js 20.11+ (managed via Volta)
- pnpm 8.15+
- PostgreSQL 15+
- Redis 7+ (optional)

## Quick Start

1. **Clone repository**
   ```bash
   git clone <repo-url>
   cd <repo-name>
   ```

2. Install tools (if using Volta)

   curl https://get.volta.sh | bash
   # Volta will automatically use versions from package.json
   

3. Run setup script

   ./scripts/setup.sh
   

4. Configure environment

   • Copy .env.example to .env
   • Fill in required values
   • See ENVIRONMENT_VARIABLES.md for details

5. Start development server

   pnpm dev
   

Troubleshooting

Port already in use

• Kill process: lsof -ti:3000 | xargs kill

Database connection failed

• Check PostgreSQL is running: pg_isready
• Verify DATABASE_URL in .env

Node version mismatch

• Install Volta: See step 2
• Or use nvm: nvm use

Common Commands

pnpm dev          # Start dev server
pnpm build        # Build for production
pnpm test         # Run tests
pnpm lint         # Check code quality
pnpm format       # Format code

## Cross-Platform Considerations

### Shell Scripts
- Provide both .sh (Unix) and .ps1 (Windows) versions
- Or use Node.js scripts for true cross-platform

### Path Separators
- Use Node's `path.join()` in scripts
- Avoid hardcoded `/` or `\`

### Line Endings
- Configure .gitattributes:

• text=auto *.sh text eol=lf

## Version Manager Comparison

| Tool | Languages | Auto-switching | Config File |
|------|-----------|----------------|-------------|
| Volta | Node, Yarn, pnpm | Yes | package.json |
| asdf | Multi | Yes | .tool-versions |
| mise | Multi | Yes | .mise.toml |
| nvm | Node only | Manual | .nvmrc |
| pyenv | Python only | Yes | .python-version |

## Best Practices

1. **Pin exact versions** in configs to avoid surprises
2. **Document all requirements** in onboarding guide
3. **Test setup script** on clean machine
4. **Keep .env.example updated** with all variables
5. **Provide troubleshooting** for common issues
6. **Use tool version managers** over manual installs
7. **Make setup idempotent** (safe to run multiple times)

## Output Checklist

Every dev environment bootstrap should include:

- [ ] Version manager config (.tool-versions, package.json volta, etc.)
- [ ] Package manager choice documented
- [ ] .env.example with all variables
- [ ] Setup script (setup.sh or setup.js)
- [ ] SETUP.md or DEVELOPMENT.md onboarding guide
- [ ] Troubleshooting section
- [ ] Common commands reference
- [ ] Prerequisites listed