Skip to main content

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

Build Validation Best Practices

🛡️ Multi-Layer Protection Strategy​

We use multiple checkpoints to prevent failed builds from reaching Vercel:

1. Local Checks (Immediate feedback)​

Pre-commit Hook​

  • Runs on every git commit
  • Fast checks: TypeScript, Lint, Format, Tests
  • ~30 seconds

Pre-push Hook​

  • Runs on git push
  • Full production build test
  • ~1-2 minutes
  • Prevents broken builds from reaching remote

2. GitHub Checks (Before merge)​

Pull Request Validation​

  • Runs on every PR
  • Full validation + build
  • Comments on PR if build fails
  • Prevents broken code from reaching main

Scheduled Health Checks​

  • Weekly automated build test
  • Creates GitHub issue if build breaks
  • Catches dependency/config drift early

3. Manual Checks (When needed)​

# Quick validation
make quick-check

# Comprehensive check (recommended before important changes)
make pre-deploy

# Or use the script directly
./scripts/pre-deploy-check.sh

🚀 Recommended Workflow​

For Regular Development​

  1. Make changes
  2. git add .
  3. git commit -m "message" → Pre-commit runs automatically
  4. git push → Pre-push runs automatically

For Important Changes​

  1. Make changes
  2. Run make pre-deploy manually
  3. Fix any issues
  4. Then commit and push

For Emergency Fixes​

# Skip pre-commit
git commit --no-verify -m "emergency fix"

# Skip pre-push
git push --no-verify

# But ALWAYS run validation after!
pnpm run validate

📊 Build Performance Tips​

1. Use PR Workflow​

  • Create PRs instead of pushing directly to main
  • Let GitHub Actions validate while you work on other tasks

2. Local Build Caching​

# Faster repeated builds
rm -rf node_modules/.vite
pnpm run build

3. Docker Build Caching​

# Use BuildKit for better caching
DOCKER_BUILDKIT=1 make docker-test

🚨 When Builds Fail​

Common Issues​

  1. TypeScript Errors

    pnpm run typecheck

  2. Linting Issues

    pnpm run lint:fix

  3. Import Errors

    • Check for missing dependencies
    • Verify import paths
    • Look for circular dependencies

  4. Environment Variables

    • Build uses dummy values for secrets
    • Real values only needed at runtime

🎯 Build Budget​

We aim to keep:

  • Local validation: < 1 minute
  • Full build: < 2 minutes
  • Docker build: < 3 minutes
  • Vercel deployment: < 3 minutes

🔧 Maintenance​

Weekly Tasks​

  • Review automated health check results

  • Update dependencies carefully:

    pnpm update --interactive
    make pre-deploy  # Test after updates

Monthly Tasks​

  • Review and optimize build size
  • Check for security updates
  • Clean up unused dependencies

💡 Pro Tips​

  1. Run validation in background:

    make pre-deploy &
    # Continue working while it runs

  2. Use Git worktrees for testing:

    git worktree add ../ocean-test
    cd ../ocean-test
    make pre-deploy

  3. Set up aliases:

    alias validate="make quick-check"
    alias predeploy="make pre-deploy"

By following these practices, you'll catch 99% of build issues before they reach Vercel!