Dependency Upgrade Plans - ericfitz/tmi GitHub Wiki

Dependency Upgrade Plans

This page documents major dependency upgrades for the TMI project, including migration strategies, breaking changes, and compatibility considerations.

Completed Upgrades

Angular 21, Vitest 4, and Marked v17 Migration

Related issues: #241, #320, #263

Status: COMPLETE

Completed in: TMI-UX v1.4.0 (dev/1.4.0 branch)

All target packages are now at stable releases and have been integrated:

Package Previous Current
@angular/core ^20.3.16 ^21.2.6
vitest ^3.2.4 ^4.1.2
marked ^16.4.2 ^17.0.5
ngx-markdown ^20.1.0 ^21.1.0

Overview

TMI-UX was migrated from:

  • Angular 20.3.16 to 21.2.6
  • Vitest 3.2.4 to 4.1.2
  • Marked 16.4.2 to 17.0.5 (via ngx-markdown 21.1.0)

Constraints:

  • AntV/X6 packages remain pinned at v2.x per user request
  • Zoneless migration deferred (58 detectChanges calls across 13 files, NgZone patterns in 6 files, X6 integration make it a multi-week effort)

Progress Tracking

  • Phase 0: Verify target versions available
  • Phase 1: Pre-Migration Verification
  • Phase 2: Update Angular Core
  • Phase 3: Update Angular Material
  • Phase 4: Update Angular ESLint
  • Phase 5: Update ngx-markdown (Breaking Change)
  • Phase 6: Update Vitest 4 (Breaking Change)
  • Phase 7: Update @analogjs/vite-plugin-angular
  • Phase 8: Final Verification

Dependency Chain

The upgrades are interconnected:

  1. ngx-markdown 21.x requires Angular 21 AND updates marked to 17.x
  2. This means Angular 21 and Marked 17 must upgrade together via ngx-markdown
  3. Vitest 4 can be done independently but makes sense to batch

Breaking Changes Summary

Package Breaking Change How It Was Resolved
ngx-markdown 21 sanitize config now uses SANITIZE injection token Markdown providers moved to lazy-loaded route configs (tm.routes.ts, triage.routes.ts) via provideMarkdownConfig() to reduce initial bundle size
Vitest 4 vi.restoreAllMocks() no longer resets vi.fn() mocks Handled via vitest config options (restoreMocks: true, clearMocks: true) instead of manual calls in test-setup.ts
Angular 21 SimpleChanges is generic (not used in codebase) No code changes needed
Marked 17 Internal tokenization changes (abstracted by ngx-markdown) No code changes needed

Compatibility Verified

Package Version Angular 21 Compatible?
@jsverse/transloco ^8.2.1 Yes (supports >=16)
zone.js ~0.16.1 Yes (latest; Angular 21 works with zone.js or zoneless)
rxjs ~7.8.2 Yes (Angular 21 requires ^6.5.3 or ^7.4.0)
typescript ~5.9.3 Yes (Angular 21 requires >=5.9.0 <6.0.0)

Phase 1: Pre-Migration Verification

git checkout -b chore/angular21-vitest4-marked17
pnpm run build
pnpm test
pnpm run lint:all

Ensure all tests pass before proceeding.

Phase 2: Update Angular Core (ng update)

ng update @angular/core@21 @angular/cli@21

This updates all @angular/* packages to 21.x:

  • @angular/animations, common, compiler, compiler-cli, core, forms
  • @angular/platform-browser, platform-browser-dynamic, router
  • @angular-devkit/build-angular, @angular/cli

Verify:

pnpm run build

Phase 3: Update Angular Material

ng update @angular/material@21

Updates @angular/material and @angular/cdk to 21.x.

Verify:

pnpm run build

Phase 4: Update Angular ESLint

ng update angular-eslint@21

Updates all @angular-eslint/* packages to 21.x.

Verify:

pnpm run lint:all

Phase 5: Update ngx-markdown (Breaking Change)

5.1 Update dependencies in package.json

Updated to:

{
  "dependencies": {
    "marked": "^17.0.5",
    "ngx-markdown": "^21.1.0"
  }
}

5.2 Migrate markdown providers to lazy-loaded routes

Rather than using the SANITIZE injection token approach originally planned, the markdown/mermaid/DOMPurify providers were moved out of the root app.config.ts into lazy-loaded route configurations (tm.routes.ts and triage.routes.ts) via a provideMarkdownConfig() helper. This reduced the initial bundle size since markdown rendering is not needed on the landing or login pages.

The root app.config.ts no longer directly references provideMarkdown(). The DOMPurify-based sanitization continues to be handled in markedOptionsFactory.

Phase 6: Update Vitest 4 (Breaking Change)

6.1 Update dependencies in package.json

Updated to:

{
  "devDependencies": {
    "vitest": "^4.1.2",
    "@vitest/coverage-v8": "^4.1.2",
    "@vitest/ui": "^4.1.2"
  }
}

6.2 Mock cleanup handled via vitest config

Rather than manually calling vi.resetAllMocks() and vi.restoreAllMocks() in test-setup.ts, the Vitest 4 mock behavior change was addressed by setting restoreMocks: true and clearMocks: true in the vitest configuration. The manual afterEach block was removed from src/test-setup.ts.

Phase 7: Update @analogjs/vite-plugin-angular

Updated to ^2.3.1, which provides stable Angular 21 support:

{
  "devDependencies": {
    "@analogjs/vite-plugin-angular": "^2.3.1"
  }
}

Phase 8: Final Verification

# Build
pnpm run build
pnpm run build:prod

# Tests
pnpm test
pnpm run test:e2e

# Lint
pnpm run lint:all
pnpm run format

Manual Testing Checklist

  • Application starts without console errors
  • Login/authentication works
  • Threat model list loads
  • Create/edit/delete threat model works
  • DFD diagram editor loads and functions (AntV/X6)
  • Note editor markdown preview renders correctly
  • Mermaid diagrams in notes render
  • Code syntax highlighting works in notes
  • Translations load (test with different locale)

Package Version Summary

Package Previous Current
@angular/* ^20.3.16 ^21.2.6
@angular/material ^20.2.14 ^21.2.4
@angular/cdk ^20.2.14 ^21.2.4
@angular-devkit/build-angular ^20.3.14 ^21.2.5
@angular/cli ^20.3.14 ^21.2.5
@angular-eslint/* ^20.7.0 ^21.3.1
ngx-markdown ^20.1.0 ^21.1.0
marked ^16.4.2 ^17.0.5
vitest ^3.2.4 ^4.1.2
@vitest/coverage-v8 ^3.2.4 ^4.1.2
@vitest/ui ^3.2.4 ^4.1.2
@analogjs/vite-plugin-angular ^2.2.2 ^2.3.1

Unchanged (verified compatible):

  • typescript: ~5.9.3 (Angular 21 requires >=5.9.0 <6.0.0)
  • zone.js: ~0.16.1 (Angular 21 supports zoneless but zone.js still works)
  • rxjs: ~7.8.2 (Angular 21 requires ^6.5.3 || ^7.4.0)
  • @jsverse/transloco: ^8.2.1 (supports Angular >=16, which includes 21)
  • @antv/x6: 2.19.2 (pinned, not updating per user request)

Critical Files Modified

  1. package.json - All dependency version updates
  2. src/app/app.config.ts - Removed direct provideMarkdown() call (moved to lazy-loaded routes)
  3. tm.routes.ts, triage.routes.ts - Added provideMarkdownConfig() for lazy-loaded markdown providers
  4. vitest.config.ts (or equivalent) - Added restoreMocks: true, clearMocks: true
  5. src/test-setup.ts - Removed manual vi.restoreAllMocks() afterEach block

Rollback Plan

If critical issues are discovered:

git checkout main
pnpm install

The migration branch can be preserved for debugging.

Risk Assessment (Retrospective)

Risk Impact Outcome
@analogjs/vite-plugin-angular not yet Angular 21 compatible High Resolved: v2.3.1 supports Angular 21
ngx-markdown SANITIZE change breaks markdown Medium Resolved: Moved to lazy-loaded route providers
Vitest 4 mock changes cause test failures Medium Resolved: Handled via vitest config options
Angular Material 21 component API changes Low No issues encountered

Future: Zoneless Migration (Deferred)

Angular 21 defaults to zoneless for new apps. This codebase will continue using zone.js for now due to:

  • 58 detectChanges() calls across 13 files (heavy in DFD/collaboration, dashboard, triage, inline-edit)
  • 17 NgZone usages across 6 files for performance optimization (activity tracking, session management, token validity)
  • AntV/X6 graph events fire outside Angular context
  • Test infrastructure depends on zone.js

When ready to migrate zoneless:

  1. Replace provideZoneChangeDetection() with provideExperimentalZonelessChangeDetection()
  2. Refactor NgZone patterns in ActivityTrackerService and SessionManagerService
  3. Convert collaboration state to signals to eliminate manual detectChanges()
  4. Update test infrastructure (remove zone.js imports, replace fakeAsync/tick)
  5. Estimated effort: 6-8 weeks

Related Documentation