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