knaxuslearn · build · ship

Roadmaps / TypeScript / Phase 3

Phase 3 of 4 · Study weeks 9-12

The compiler, the build and the move to TypeScript 7

This phase makes the third checkpoint possible: a build that is fast, correct for consumers and ready for the native compiler.

Topics every week

  1. Week 98 h
    • tsconfig and module resolution (nodenext and bundler)
    • ES modules and CommonJS in TypeScript
    • verbatimModuleSyntax and import type
    • Running .ts with type stripping (check your Node version)

    Hand inA library consumed under three resolution modes, with a passing matrix

  2. Week 108 h
    • Project references and incremental builds
    • Declaration output and exports with types
    • The attw check
    • Monorepo layout with pnpm

    Hand inA three-package workspace where a change rebuilds only what it must

  3. Week 118 h
    • TypeScript 6 and TypeScript 7: what changed
    • Deprecations that became errors
    • Running TypeScript 6 side by side
    • Tools that need the old compiler API

    Hand inA migration plan with a branch, a rollback step and a tool compatibility table

  4. Week 128 h
    • Type performance: instantiations and depth
    • --extendedDiagnostics
    • --generateTrace and a trace viewer
    • Simplifying a slow type

    Hand inCheckpoint 3, with predicted and measured numbers side by side

Practice projects

  • Practice 1, the resolution matrix (Week 9): consume one library from nodenext, bundler and CommonJS settings. Done when: the matrix passes in CI and attw reports no errors for the package.
  • Practice 2, project references (Week 10): split the workspace into three projects. Done when: tsc -b log shows only the changed project rebuilding, and an incremental rebuild takes under 20% of a clean build.
  • Practice 3, the slow-type hunt (Week 12): find the slowest type with --generateTrace. Done when: a before and after table shows instantiations and check time, with a drop of at least 30% or a written reason why not.
  • Optional, run .ts directly: run the server with Node's type stripping and erasableSyntaxOnly. Done when: it starts, and you list the syntax you had to change (enums, namespaces, parameter properties).

GitHub repos to study

Existence, last commit and README notices were checked on 22 Nov 2026 by shallow clone. Every repository below had a commit in the last six months. Archive status comes from the README, not from the GitHub setting, so look again before you rely on one.

RepoWhat to readWeek
microsoft/TypeScriptThe native compiler now lives here (the staging repo microsoft/typescript-go is closed and will be archived), plus the performance notes and tsconfig reference11
typescript-eslint/typescript-eslintHow a type-aware linter uses the compiler API, and what it needs from 7.111
arethetypeswrong/arethetypeswrong.github.ioThe checks behind attw and what each failure means10
vitest-dev/vitestType tests in a test runner (its typecheck mode)9

Milestone checkpoint

Run Checkpoint 3. Set a budget first: measure the full check of the 60-endpoint file on TypeScript 6, and write down the speed-up you expect from TypeScript 7 before you run it. Then measure both compilers three times each and report the medians. Capture a trace, fix the slowest type, and measure again. Move the workspace to TypeScript 7 on a branch, keep TypeScript 6 installed side by side for tools that still need the old compiler API, and write the rollback. Hand in the timing table, the trace summaries, the compatibility table, ADR-5 (what you pinned and when you upgrade) and the rollback step.

Check yourself

Answer each question in your head first, then open it to check.

  1. What does verbatimModuleSyntax do?
    It keeps imports and exports as you wrote them and requires import type for type-only imports, so the emitted code matches the source and single-file tools work.
  2. What is the difference between nodenext and bundler module resolution?
    nodenext follows Node's rules (file extensions in ES modules, the exports map). bundler allows extensionless imports and assumes a bundler resolves them.
  3. Why can a tool still need TypeScript 6 after TypeScript 7 is released?
    TypeScript 7 is a rewrite in Go, and its stable programmatic API is expected in 7.1. Tools that call the compiler API (for example linters with type-aware rules, and some bundler loaders) use TypeScript 6 side by side until then.
  4. What do project references buy you?
    Builds of only the projects that changed, enforced boundaries between packages, and editor support per project.
  5. What does a --generateTrace file show?
    Time spent per file and per type, so you can open it in a trace viewer and see which type or file dominates the check.