name: Local Development Standard description: Standardized local development environment setup ensuring consistency across team members and reducing "works on my machine" issues.

Local Development Standard

Overview

Local Development Standards define how developers set up and run projects on their machines, ensuring consistency, reproducibility, and minimal onboarding friction.

Core Principle: "New developers should be productive in under 30 minutes."

1. One-Command Setup

# The ideal: Single command to get started
npm run setup

# Or
make setup

# Or
./scripts/setup.sh

Setup Script Example

#!/bin/bash
# scripts/setup.sh

echo "🚀 Setting up development environment..."

# Check prerequisites
command -v node >/dev/null 2>&1 || { echo "Node.js required"; exit 1; }
command -v docker >/dev/null 2>&1 || { echo "Docker required"; exit 1; }

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Start Docker services
docker-compose up -d

# Run database migrations
npm run db:migrate

# Seed database
npm run db:seed

echo "✅ Setup complete! Run 'npm run dev' to start"

2. Environment Configuration

.env.example

# .env.example - Committed to repo
DATABASE_URL=postgresql://localhost:5432/myapp_dev
REDIS_URL=redis://localhost:6379
API_KEY=your_api_key_here
NODE_ENV=development

.env - Not committed

# .env - Local only, gitignored
DATABASE_URL=postgresql://localhost:5432/myapp_dev
REDIS_URL=redis://localhost:6379
API_KEY=actual_secret_key_12345
NODE_ENV=development

3. Docker Compose for Dependencies

# docker-compose.yml
version: '3.8'

services:
  postgres:
    image: postgres:15
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: myapp_dev
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpass
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7
    ports:
      - "6379:6379"

  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"  # SMTP
      - "8025:8025"  # Web UI

volumes:
  postgres_data:

4. Package.json Scripts

{
  "scripts": {
    "setup": "./scripts/setup.sh",
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test": "jest",
    "test:watch": "jest --watch",
    "lint": "eslint .",
    "format": "prettier --write .",
    "type-check": "tsc --noEmit",
    "db:migrate": "prisma migrate dev",
    "db:seed": "prisma db seed",
    "db:reset": "prisma migrate reset",
    "docker:up": "docker-compose up -d",
    "docker:down": "docker-compose down"
  }
}

5. README Development Section

## Development Setup

### Prerequisites
- Node.js 18+
- Docker Desktop
- Git

### Quick Start
\`\`\`bash
# Clone repository
git clone https://github.com/company/project.git
cd project

# Run setup
npm run setup

# Start development server
npm run dev
\`\`\`

### Available Commands
- `npm run dev` - Start development server
- `npm run test` - Run tests
- `npm run lint` - Lint code
- `npm run db:migrate` - Run database migrations

### Troubleshooting
- **Port 3000 already in use**: Run `lsof -ti:3000 | xargs kill`
- **Database connection failed**: Ensure Docker is running

6. VS Code Workspace Settings

// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "files.exclude": {
    "**/.git": true,
    "**/node_modules": true,
    "**/.next": true
  }
}

Recommended Extensions

// .vscode/extensions.json
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "prisma.prisma",
    "ms-azuretools.vscode-docker"
  ]
}

7. Hot Reload Configuration

Next.js

// next.config.js
module.exports = {
  reactStrictMode: true,
  webpack: (config) => {
    config.watchOptions = {
      poll: 1000,
      aggregateTimeout: 300,
    };
    return config;
  },
};

Vite

// vite.config.ts
export default defineConfig({
  server: {
    watch: {
      usePolling: true,
    },
    hmr: {
      overlay: true,
    },
  },
});

8. Local Development Checklist

• One-Command Setup: Can new devs start with single command?
• .env.example: Example environment file committed?
• Docker Compose: Dependencies containerized?
• README: Clear setup instructions?
• VS Code Settings: Workspace settings committed?
• Hot Reload: Fast feedback loop configured?
• Seed Data: Test data available for local dev?
• Troubleshooting: Common issues documented?

Related Skills

• 45-developer-experience/onboarding-docs
• 45-developer-experience/dev-environment-setup
• 45-developer-experience/hot-reload-fast-feedback