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
- Week 98 h
tsconfigand module resolution (nodenextandbundler)- ES modules and CommonJS in TypeScript
verbatimModuleSyntaxandimport type- Running
.tswith type stripping (check your Node version)
Hand inA library consumed under three resolution modes, with a passing matrix
- Week 108 h
- Project references and incremental builds
- Declaration output and
exportswith types - The
attwcheck - Monorepo layout with pnpm
Hand inA three-package workspace where a change rebuilds only what it must
- 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
- Week 128 h
- Type performance: instantiations and depth
--extendedDiagnostics--generateTraceand 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,bundlerand CommonJS settings. Done when: the matrix passes in CI andattwreports no errors for the package. - Practice 2, project references (Week 10): split the workspace into three projects. Done when:
tsc -blog 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
.tsdirectly: run the server with Node's type stripping anderasableSyntaxOnly. 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.
| Repo | What to read | Week |
|---|---|---|
| microsoft/TypeScript | The native compiler now lives here (the staging repo microsoft/typescript-go is closed and will be archived), plus the performance notes and tsconfig reference | 11 |
| typescript-eslint/typescript-eslint | How a type-aware linter uses the compiler API, and what it needs from 7.1 | 11 |
| arethetypeswrong/arethetypeswrong.github.io | The checks behind attw and what each failure means | 10 |
| vitest-dev/vitest | Type 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.
What does
verbatimModuleSyntaxdo?It keeps imports and exports as you wrote them and requiresimport typefor type-only imports, so the emitted code matches the source and single-file tools work.What is the difference between
nodenextandbundlermodule resolution?nodenextfollows Node's rules (file extensions in ES modules, theexportsmap).bundlerallows extensionless imports and assumes a bundler resolves them.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.What do project references buy you?
Builds of only the projects that changed, enforced boundaries between packages, and editor support per project.What does a
--generateTracefile 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.