Skip to main content

Source: ocean/docs/BUILD_VALIDATION.md | ✏️ Edit on GitHub

Build Validation Strategy

Overview​

We use multiple layers of validation to ensure code quality before deploying to Vercel:

  1. Local Git Hooks - Immediate feedback on commit
  2. Docker Testing - Consistent environment testing
  3. GitHub Actions CI - Automated validation on push/PR
  4. Vercel Preview Deployments - Final validation

Local Development​

Quick Validation​

# Run type checking and tests
pnpm run validate

# Or use Make
make validate

Docker Testing​

# Test build in Docker (same as Vercel environment)
make docker-test

# Run full production build locally
make docker-prod
# Visit http://localhost:8080

Pre-Deployment Checklist​

Before pushing to main:

# Run complete validation suite
make pre-deploy

This runs:

  1. TypeScript type checking
  2. All tests
  3. Docker build test
  4. Production build verification

Git Hooks​

Husky automatically runs validation on commit:

  • TypeScript build check
  • Test suite execution

To skip hooks in emergency:

git commit --no-verify -m "Emergency fix"

CI/CD Pipeline​

GitHub Actions runs on every push:

  1. Validate Job: Linting, type checking, tests
  2. Docker Build: Tests both dev and production builds
  3. Deploy Check: Simulates Vercel build

Docker Commands​

# Development with hot reload
docker-compose up dev

# Run tests in container
docker-compose run --rm test

# Production preview
docker-compose up prod

# Clean rebuild
docker-compose build --no-cache

Troubleshooting​

Build fails locally but not in Docker​

# Clean and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

Docker build is slow​

# Use BuildKit for better caching
DOCKER_BUILDKIT=1 docker build .

Type errors not caught​

# Run strict type check
pnpm run typecheck

Best Practices​

  1. Always run make validate before pushing
  2. Use Docker for production-like testing
  3. Don't skip CI checks
  4. Fix warnings, not just errors
  5. Keep dependencies up to date

Environment Variables​

For Docker testing with real services:

# Create .env.docker
cp .env .env.docker
# Edit as needed

# Run with env file
docker-compose --env-file .env.docker up test