cmdb-insight/docs/TYPESCRIPT-LOCAL-VS-CI.md

Waarom TypeScript Errors Lokaal Niet Optreden Maar Wel in CI/CD

Het Probleem

TypeScript compilation errors die lokaal niet optreden, maar wel in Azure DevOps pipelines of Docker builds. Dit is een veelvoorkomend probleem met verschillende oorzaken.

Belangrijkste Oorzaken

1. tsx vs tsc - Development vs Production Build

Lokaal (Development):

npm run dev  # Gebruikt: tsx watch src/index.ts

In Docker/CI (Production Build):

npm run build  # Gebruikt: tsc (TypeScript Compiler)

Verschil:

• tsx (TypeScript Execute): Een runtime TypeScript executor die code direct uitvoert zonder volledige type checking. Het is minder strict en laat veel type errors door.
• tsc (TypeScript Compiler): De officiële TypeScript compiler die volledige type checking doet en alle errors rapporteert.

Oplossing:

• Test altijd lokaal met npm run build voordat je pusht
• Of gebruik tsc --noEmit om type checking te doen zonder te builden

2. TypeScript Versie Verschillen

Lokaal:

npx tsc --version  # Kan een andere versie zijn

In Docker:

• Gebruikt de versie uit package.json ("typescript": "^5.6.3")
• Maar zonder package-lock.json kan een andere patch versie geïnstalleerd worden

Oplossing:

• Genereer package-lock.json met npm install
• Commit package-lock.json naar Git
• Dit zorgt voor consistente dependency versies

3. tsconfig.json Strictness

Je tsconfig.json heeft "strict": true, wat betekent:

• Alle strict type checking opties zijn aan
• Dit is goed voor productie, maar kan lokaal vervelend zijn

Mogelijke verschillen:

• Lokaal kan je IDE/editor andere TypeScript settings hebben
• Lokaal kan je tsconfig.json overrides hebben
• CI/CD gebruikt altijd de exacte tsconfig.json uit de repo

4. Node.js Versie Verschillen

Lokaal:

• Kan een andere Node.js versie hebben
• TypeScript gedrag kan verschillen tussen Node versies

In Docker:

FROM node:20-alpine  # Specifieke Node versie

Oplossing:

• Gebruik .nvmrc of package.json engines field om Node versie te specificeren
• Zorg dat lokaal dezelfde Node versie gebruikt wordt

5. Cached Builds

Lokaal:

• Oude compiled files in dist/ kunnen nog werken
• IDE kan gecachte type informatie gebruiken
• tsx gebruikt geen build output, dus errors worden niet altijd gezien

In CI/CD:

• Schone build elke keer
• Geen cache, dus alle errors worden gezien

6. Incremental Compilation

Lokaal:

• TypeScript kan incremental compilation gebruiken
• Alleen gewijzigde files worden gecheckt

In CI/CD:

• Volledige rebuild elke keer
• Alle files worden gecheckt

Best Practices om Dit Te Voorkomen

1. Test Lokaal Met Production Build

# Voordat je pusht, test altijd:
cd backend
npm run build  # Dit gebruikt tsc, net als in Docker

2. Type Checking Zonder Build

# Alleen type checking, geen build:
npx tsc --noEmit

3. Pre-commit Hooks

Voeg een pre-commit hook toe die tsc --noEmit draait:

// package.json
{
  "scripts": {
    "type-check": "tsc --noEmit",
    "precommit": "npm run type-check"
  }
}

4. Genereer package-lock.json

# Genereer lock file voor consistente dependencies:
npm install

# Commit package-lock.json naar Git
git add package-lock.json
git commit -m "Add package-lock.json for consistent builds"

5. Gebruik CI/CD Lokaal

Test je pipeline lokaal met:

• act (voor GitHub Actions)
• Azure DevOps Pipeline Agent lokaal
• Docker build lokaal: docker build -f backend/Dockerfile.prod -t test-build ./backend

6. IDE TypeScript Settings

Zorg dat je IDE dezelfde TypeScript versie gebruikt:

• VS Code: Check "TypeScript: Select TypeScript Version"
• Gebruik "Use Workspace Version"

Voor Dit Project Specifiek

Huidige Situatie

1. Development: tsx watch - minder strict
2. Production Build: tsc - volledig strict
3. Geen package-lock.json - verschillende dependency versies mogelijk
4. TypeScript 5.6.3 in package.json, maar lokaal mogelijk 5.9.3

Aanbevolen Acties

1. Genereer package-lock.json:

   cd backend
   npm install
   git add package-lock.json
   git commit -m "Add package-lock.json"
   

2. Test altijd met build:

   npm run build  # Voordat je pusht
   

3. Voeg type-check script toe:

   {
     "scripts": {
       "type-check": "tsc --noEmit"
     }
   }
   

4. Test Docker build lokaal:

   docker build -f backend/Dockerfile.prod -t test-backend ./backend
   

Conclusie

Het verschil komt vooral door:

• tsx (dev) vs tsc (build) - tsx is minder strict
• Geen package-lock.json - verschillende dependency versies
• Cached builds lokaal - oude code werkt nog

Oplossing: Test altijd met npm run build lokaal voordat je pusht, en genereer package-lock.json voor consistente builds.