Docker Build Consistency Guide

This guide ensures your local development matches the Docker build environment exactly, preventing build failures in the cloud.

Problem

The Docker build runs stricter checks than your local development might, leading to:

  • ✅ Local builds passing
  • ❌ Docker builds failing
  • 😤 Frustration and wasted time

Solution

Updated configurations and scripts to match Docker build exactly.

Changes Made

1. Updated tsconfig.json

  • Include: All TypeScript files including tests (matches Docker)
  • Exclude: Only necessary directories (.next, out, node_modules)
  • Strict mode: Enabled to catch more issues early

2. Added New NPM Scripts

npm run typecheck

Runs the exact TypeScript check that Docker uses:

npx tsc --noEmit

npm run quality:check

Runs all quality checks in sequence:

npm run lint && npm run typecheck && npm run test:run && npm run build

npm run docker:check

Runs the complete Docker build simulation:

bash scripts/docker-check.sh

3. Created scripts/docker-check.sh

Complete simulation of Docker build process including:

  • Environment info display
  • Linting (npm run lint)
  • TypeScript checking (npx tsc --noEmit)
  • Testing (CI=true npm run test:run)
  • Building (npm run build)

How to Use

Before Pushing Code

Run this to catch issues locally:

npm run quality:check

Full Docker Simulation

Run this to simulate the complete Docker build:

npm run docker:check

Individual Checks

# TypeScript only (matches Docker)
npm run typecheck

# Linting only
npm run lint

# Tests only (CI mode)
CI=true npm run test:run

# Build only
npm run build

Docker Build Process

The Docker build (Dockerfile lines 66-88) runs exactly these commands:

  1. Linting: npm run lint
  2. TypeScript: npx tsc --noEmit (includes ALL files)
  3. Testing: CI=true npm run test:run --reporter=basic --coverage=false --run
  4. Building: npm run build

Key Differences From Before

TypeScript Checking

  • Before: Might exclude test files locally
  • Now: Includes ALL TypeScript files (matches Docker)
  • Result: Catch test TypeScript errors locally

Test Environment

  • Before: Different test settings local vs Docker
  • Now: CI=true mode matches Docker exactly
  • Result: Consistent test behavior

Build Environment

  • Before: Different environment variables
  • Now: Same telemetry and Node options as Docker
  • Result: Identical build process

Development

# Regular development
npm run dev

# Before committing
npm run quality:check

Pre-Push Checklist

npm run docker:check

If Docker Build Fails

  1. Run npm run docker:check locally
  2. Fix any issues that appear
  3. Push again

Environment Variables

The Docker build uses these environment settings:

NEXT_TELEMETRY_DISABLED=1
CI=true (for tests)
NODE_OPTIONS="--dns-result-order=ipv4first"

These are now replicated in the local scripts.

File Structure

frontend/
├── tsconfig.json          # Updated to match Docker
├── package.json           # Added new scripts
├── scripts/
│   └── docker-check.sh    # Full Docker simulation
└── DOCKER_CONSISTENCY.md  # This guide

Benefits

✅ Catch issues early: Find problems locally before cloud build ✅ Faster feedback: No waiting for cloud build to fail ✅ Consistent environment: Local development matches production ✅ Time savings: Fix issues locally instead of debugging cloud failures ✅ Confidence: Know your code will pass Docker build before pushing

Troubleshooting

“Command not found: bash”

On Windows, use Git Bash or WSL to run the shell script.

TypeScript errors in tests

The new config includes test files in TypeScript checking (like Docker does). Fix TypeScript errors in test files rather than excluding them.

Different Node version

Docker uses Node 18. Consider using the same version locally:

nvm use 18  # if using nvm

Summary

Now your local environment exactly matches the Docker build environment. Run npm run docker:check before pushing to ensure your code will pass the cloud build process.