Full Stack Development - jvPalma/dotrun GitHub Wiki

Full-Stack Development Workflow

Complete workflow guide for web development teams using React frontend, Node.js backend, and PostgreSQL database.

Team Structure

  • 3 Frontend developers
  • 2 Backend developers
  • 1 Full-stack developer
  • 1 DevOps engineer

Collection Setup

Repository: company/fullstack-tools

# Initialize collection
mkdir fullstack-tools && cd fullstack-tools
dr export . fullstack-tools --git

# Create collection structure
mkdir -p bin/{frontend,backend,database,deployment}
mkdir -p docs/{frontend,backend,database,deployment}
mkdir -p helpers

Collection Metadata (dotrun.collection.yml):

name: "fullstack-tools"
description: "Complete web development workflow tools"
author: "Development Team"
version: "1.0.0"
dependencies:
  - node
  - npm
  - docker
  - git
  - psql
optional_dependencies:
  - yarn
  - docker-compose
  - heroku
categories:
  - frontend
  - backend
  - database
  - deployment

Frontend Scripts

Development Server

bin/frontend/dev-server.sh:

#!/usr/bin/env bash
### DOC
# Start React development server with hot reload
# Includes environment setup and dependency checks
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/pkg.sh"
validatePkg node npm

main() {
  if [[ ! -f "package.json" ]]; then
    echo "โŒ No package.json found. Run from React project root."
    exit 1
  fi

  echo "๐Ÿš€ Starting React development server..."

  # Install dependencies if node_modules missing
  if [[ ! -d "node_modules" ]]; then
    echo "๐Ÿ“ฆ Installing dependencies..."
    npm install
  fi

  # Start development server
  BROWSER=none npm start

  echo "โœ… Development server started at http://localhost:3000"
}

main "$@"

Production Build

bin/frontend/build-production.sh:

#!/usr/bin/env bash
### DOC
# Build optimized production React bundle
# Includes bundle analysis and size warnings
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/pkg.sh"
validatePkg node npm

main() {
  echo "๐Ÿ—๏ธ  Building production React app..."

  # Clean previous build
  rm -rf build/

  # Build with production optimizations
  NODE_ENV=production npm run build

  # Show build info
  echo "๐Ÿ“Š Build completed!"
  echo "๐Ÿ“ Build size:"
  du -sh build/

  # Check for large files
  echo "๐Ÿ” Large files (>500KB):"
  find build/ -size +500k -type f -exec ls -lh {} \; | awk '{ print $5 "\t" $9 }'

  echo "โœ… Production build ready in build/ directory"
}

main "$@"

Testing Scripts

bin/frontend/run-tests.sh:

#!/usr/bin/env bash
### DOC
# Run comprehensive frontend test suite
# Includes unit tests, integration tests, and coverage
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/pkg.sh"
validatePkg node npm

main() {
  local test_type="${1:-all}"

  echo "๐Ÿงช Running frontend tests: $test_type"

  case "$test_type" in
    unit)
      npm run test:unit -- --coverage
      ;;
    integration)
      npm run test:integration
      ;;
    e2e)
      npm run test:e2e
      ;;
    all | *)
      echo "๐Ÿ”ฌ Running unit tests..."
      npm run test:unit -- --coverage

      echo "๐Ÿ”— Running integration tests..."
      npm run test:integration

      echo "๐ŸŒ Running E2E tests..."
      npm run test:e2e
      ;;
  esac

  echo "โœ… Frontend tests completed!"
}

main "$@"

Backend Scripts

Development Server

bin/backend/dev-server.sh:

#!/usr/bin/env bash
### DOC
# Start Node.js backend with auto-restart
# Includes database connection check
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/pkg.sh"
validatePkg node npm

main() {
  if [[ ! -f "server.js" && ! -f "app.js" && ! -f "index.js" ]]; then
    echo "โŒ No main server file found"
    exit 1
  fi

  echo "๐Ÿš€ Starting Node.js development server..."

  # Check database connection
  if ! dr backend/check-db-connection; then
    echo "โš ๏ธ  Database connection failed, starting anyway..."
  fi

  # Install dependencies
  if [[ ! -d "node_modules" ]]; then
    npm install
  fi

  # Start with nodemon for auto-restart
  if command -v nodemon >/dev/null; then
    nodemon server.js
  else
    echo "๐Ÿ’ก Tip: Install nodemon for auto-restart: npm install -g nodemon"
    node server.js
  fi
}

main "$@"

Database Connection Check

bin/backend/check-db-connection.sh:

#!/usr/bin/env bash
### DOC
# Verify database connection and schema
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/pkg.sh"
validatePkg psql

main() {
  local db_url="${DATABASE_URL:-postgresql://localhost:5432/myapp}"

  echo "๐Ÿ” Checking database connection..."

  if psql "$db_url" -c "SELECT 1;" >/dev/null 2>&1; then
    echo "โœ… Database connection successful"

    # Check if tables exist
    local table_count
    table_count=$(psql "$db_url" -t -c "SELECT count(*) FROM information_schema.tables WHERE table_schema = 'public';" | xargs)

    echo "๐Ÿ“Š Found $table_count tables in database"
    return 0
  else
    echo "โŒ Database connection failed"
    echo "๐Ÿ’ก Check DATABASE_URL: $db_url"
    return 1
  fi
}

main "$@"

API Testing

bin/backend/test-api.sh:

#!/usr/bin/env bash
### DOC
# Test API endpoints with comprehensive checks
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/pkg.sh"
validatePkg curl jq

main() {
  local base_url="${1:-http://localhost:3001}"

  echo "๐Ÿ” Testing API endpoints at $base_url"

  # Health check
  echo "๐Ÿฅ Checking health endpoint..."
  if curl -s "$base_url/health" | jq -e '.status == "ok"' >/dev/null; then
    echo "โœ… Health check passed"
  else
    echo "โŒ Health check failed"
    return 1
  fi

  # Test authentication
  echo "๐Ÿ” Testing authentication..."
  local token
  token=$(curl -s -X POST "$base_url/auth/login" \
    -H "Content-Type: application/json" \
    -d '{"username":"test","password":"test"}' | jq -r '.token')

  if [[ "$token" != "null" && -n "$token" ]]; then
    echo "โœ… Authentication successful"
  else
    echo "โŒ Authentication failed"
    return 1
  fi

  # Test protected endpoint
  echo "๐Ÿ›ก๏ธ  Testing protected endpoint..."
  if curl -s "$base_url/api/user" \
    -H "Authorization: Bearer $token" | jq -e '.id' >/dev/null; then
    echo "โœ… Protected endpoint accessible"
  else
    echo "โŒ Protected endpoint failed"
    return 1
  fi

  echo "โœ… All API tests passed!"
}

main "$@"

Database Scripts

Development Setup

bin/database/setup-dev.sh:

#!/usr/bin/env bash
### DOC
# Set up development database with sample data
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/pkg.sh"
validatePkg psql docker

main() {
  local db_name="${1:-myapp_dev}"

  echo "๐Ÿ—„๏ธ  Setting up development database: $db_name"

  # Start PostgreSQL with Docker if not running
  if ! pgrep -x "postgres" >/dev/null; then
    echo "๐Ÿณ Starting PostgreSQL with Docker..."
    docker run -d \
      --name postgres-dev \
      -e POSTGRES_DB="$db_name" \
      -e POSTGRES_USER=dev \
      -e POSTGRES_PASSWORD=password \
      -p 5432:5432 \
      postgres:13

    echo "โณ Waiting for PostgreSQL to start..."
    sleep 5
  fi

  # Run migrations
  if [[ -f "migrations/init.sql" ]]; then
    echo "๐Ÿ”„ Running migrations..."
    psql "postgresql://dev:password@localhost:5432/$db_name" <migrations/init.sql
  fi

  # Load sample data
  if [[ -f "seeds/sample_data.sql" ]]; then
    echo "๐ŸŒฑ Loading sample data..."
    psql "postgresql://dev:password@localhost:5432/$db_name" <seeds/sample_data.sql
  fi

  echo "โœ… Development database ready!"
  echo "๐Ÿ”— Connection string: postgresql://dev:password@localhost:5432/$db_name"
}

main "$@"

Migration Runner

bin/database/migrate.sh:

#!/usr/bin/env bash
### DOC
# Run database migrations with rollback support
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/pkg.sh"
validatePkg psql

main() {
  local action="${1:-up}"
  local db_url="${DATABASE_URL:-postgresql://dev:password@localhost:5432/myapp_dev}"

  echo "๐Ÿ”„ Running database migrations: $action"

  case "$action" in
    up)
      echo "โฌ†๏ธ  Applying migrations..."
      for migration in migrations/*.up.sql; do
        if [[ -f "$migration" ]]; then
          echo "๐Ÿ“ Applying $(basename "$migration")"
          psql "$db_url" <"$migration"
        fi
      done
      ;;
    down)
      echo "โฌ‡๏ธ  Rolling back migrations..."
      for migration in migrations/*.down.sql; do
        if [[ -f "$migration" ]]; then
          echo "โ†ฉ๏ธ  Rolling back $(basename "$migration")"
          psql "$db_url" <"$migration"
        fi
      done
      ;;
    status)
      echo "๐Ÿ“Š Migration status..."
      psql "$db_url" -c "SELECT * FROM schema_migrations ORDER BY version DESC LIMIT 10;"
      ;;
    *)
      echo "Usage: dr database/migrate [up|down|status]"
      exit 1
      ;;
  esac

  echo "โœ… Migration $action completed!"
}

main "$@"

Deployment Scripts

Staging Deployment

bin/deployment/deploy-staging.sh:

#!/usr/bin/env bash
### DOC
# Deploy full-stack application to staging environment
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/git.sh"
source "$DR_CONFIG/helpers/pkg.sh"
validatePkg git docker

main() {
  echo "๐Ÿš€ Deploying to staging environment..."

  # Ensure we're on main branch
  local current_branch
  current_branch=$(git_current_branch)
  if [[ "$current_branch" != "main" ]]; then
    echo "โŒ Must deploy from main branch (currently on $current_branch)"
    exit 1
  fi

  # Build frontend
  echo "๐Ÿ—๏ธ  Building frontend..."
  cd frontend/
  dr fullstack/build-production
  cd ..

  # Build backend Docker image
  echo "๐Ÿณ Building backend Docker image..."
  docker build -t myapp-backend:staging backend/

  # Deploy with docker-compose
  echo "๐Ÿ“ฆ Deploying with docker-compose..."
  docker-compose -f docker-compose.staging.yml up -d

  # Wait for services
  echo "โณ Waiting for services to start..."
  sleep 30

  # Health check
  if dr deployment/health-check staging; then
    echo "โœ… Staging deployment successful!"
    echo "๐ŸŒ Frontend: https://staging.myapp.com"
    echo "๐Ÿ”— API: https://api-staging.myapp.com"
  else
    echo "โŒ Health check failed"
    dr deployment/rollback staging
    exit 1
  fi
}

main "$@"

Health Check

bin/deployment/health-check.sh:

#!/usr/bin/env bash
### DOC
# Comprehensive health check for deployed application
### DOC
set -euo pipefail

source "$DR_CONFIG/helpers/pkg.sh"
validatePkg curl

main() {
  local environment="${1:-staging}"

  case "$environment" in
    staging)
      local frontend_url="https://staging.myapp.com"
      local api_url="https://api-staging.myapp.com"
      ;;
    production)
      local frontend_url="https://myapp.com"
      local api_url="https://api.myapp.com"
      ;;
    *)
      echo "โŒ Unknown environment: $environment"
      exit 1
      ;;
  esac

  echo "๐Ÿฅ Running health checks for $environment..."

  # Check frontend
  echo "๐ŸŒ Checking frontend at $frontend_url..."
  if curl -s -f "$frontend_url" >/dev/null; then
    echo "โœ… Frontend is accessible"
  else
    echo "โŒ Frontend health check failed"
    return 1
  fi

  # Check API health endpoint
  echo "๐Ÿ”— Checking API at $api_url..."
  if curl -s "$api_url/health" | grep -q "ok"; then
    echo "โœ… API is healthy"
  else
    echo "โŒ API health check failed"
    return 1
  fi

  # Check database connectivity
  echo "๐Ÿ—„๏ธ  Checking database connectivity..."
  if curl -s "$api_url/health/db" | grep -q "connected"; then
    echo "โœ… Database is connected"
  else
    echo "โŒ Database connectivity check failed"
    return 1
  fi

  echo "โœ… All health checks passed for $environment!"
}

main "$@"

Team Usage

Daily Developer Workflow

# Team member imports collection
dr import [email protected]:company/fullstack-tools.git fs

# Start development environment
dr fs/database/setup-dev
dr fs/backend/dev-server &
dr fs/frontend/dev-server

# Run tests before committing
dr fs/frontend/run-tests
dr fs/backend/test-api

# Build and test
dr fs/frontend/build-production
dr fs/backend/run-tests

# Deploy to staging
dr fs/deployment/deploy-staging

Code Review Workflow

# Reviewer runs automated checks
dr fs/frontend/run-tests unit
dr fs/backend/test-api http://localhost:3001
dr fs/deployment/health-check staging

# Performance testing
dr fs/frontend/build-production
ls -la frontend/build/ # Check bundle sizes

Release Workflow

# Final testing
dr fs/frontend/run-tests all
dr fs/backend/test-api

# Deploy to staging for final QA
dr fs/deployment/deploy-staging
dr fs/deployment/health-check staging

# Production deployment (after approval)
dr fs/deployment/deploy-production
dr fs/deployment/health-check production

Integration with CI/CD

GitHub Actions Integration

name: Full-Stack CI/CD
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install DotRun
        run: curl -fsSL https://raw.githubusercontent.com/jvPalma/dotrun/master/install.sh | sh
      - name: Import team tools
        run: dr import . fs
      - name: Run frontend tests
        run: dr fs/frontend/run-tests
      - name: Run backend tests
        run: dr fs/backend/test-api

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to staging
        run: dr fs/deployment/deploy-staging

Best Practices

Script Organization

  • Keep scripts focused on single responsibilities
  • Use consistent naming conventions
  • Document all environment dependencies
  • Include comprehensive error handling

Team Collaboration

  • Regular collection updates with team sync
  • Code review for shared scripts
  • Consistent environment setup across team
  • Documentation maintenance

Environment Management

  • Separate configurations for dev/staging/production
  • Environment-specific scripts and settings
  • Secure credential management
  • Automated environment setup

This full-stack workflow provides a complete development pipeline that scales from individual developers to large teams while maintaining consistency and reliability across all environments.

โš ๏ธ **GitHub.com Fallback** โš ๏ธ