0096. duolith check runs the real TypeScript checker, and every build and dev server runs it
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only)
- Planning item: none
Context
A type error in a page built silently: duolith build stripped types with oxc and never ran a checker. Only the editor checked types, so CI and anyone not using the language server never saw them. The build must fail loudly, report errors where they are written, and agree with the editor exactly.
Decision
- **
duolith check [project]** runs every checkduolith buildmakes, structure and types, and writes nothing.duolith buildandduolith devrun the same checks before they write anything. A type error is a build error with an E-code (E0340 to E0349, by kind, with TypeScript's message and number), at the page file's line and column, with the line printed under it. Induolith devit shows in the browser's error page and the terminal, like any build error. - The checker is the real TypeScript compiler API, in a small Node program,
packages/checker. For each page and component the CLI makes the script view withcrates/script-view(the crate the editor's WebAssembly uses, not a copy) and sends it on standard input. The checker builds one program for the whole project with Volar'sproxyCreateProgramand the language server's own language plugin (packages/language-server/src/page-code.ts), the same declarations and the same compiler options (src/typing.ts), so the build reports exactly what the editor does.tests/typed-markupholds a failing and a clean project for each typed position; a Rust test and a language-server test both compare against itsexpected.txt. - One run, every error. The structural checks and the type check run together. Type errors are held back only in a file that has a structural error, so every other file's are reported in the same run. The project's own
.tsfiles that pages import are in the program too, and their errors are reported in them. - **Fast enough for
duolith dev:** one program per project;duolith devkeeps the checker running, keeps every unchanged parsed file and passes the last program asoldProgram. Nothing imports a page (E0117), so when only pages changed, only those are checked again and the other pages keep their errors from last time. Each rebuild still makes a new program and type checker, which is most of its time (about 1.4 s per page edit onexamples/gallery). A language service or builder program that keeps the checker itself is the next step if that is too slow. - Never skipped, never silent. Without Node 22.18 or later the check fails with E0350; without the checker's packages, E0351. A fault in the checker is E0352: one that stops (it is started again once), one that does not answer within 180 seconds (
DUOLITH_CHECK_TIMEOUT; it is stopped, not retried), an answer that does not list every file it was asked to check underchecked, and an error in a file Duolith did not send. A view asked for with text Duolith did not send fails the check instead of checking an empty file. There is no flag to skip it.DUOLITH_NODEandDUOLITH_CHECKERstay, for machines where Node or the checker live elsewhere and for tests, and Duolith prints a warning on every run that uses one. - In this repository
@duolith/clientand@duolith/effectsresolve to their source, and@duolith/kitto a module re-exporting each part's own file, so a part's props are checked where it is placed.
Alternatives considered
| Option | Why not |
|---|---|
tsgo (@typescript/native-preview) | Faster, but still a preview, with no stable programmatic API for virtual files and language plugins; the editor runs TypeScript 5.9, and two checkers would disagree. Revisit when TypeScript 7 is stable and Volar supports it. |
tsc over generated .ts files on disk | Positions would be in generated files; mapping back would be a second implementation of the language plugin |
| A type check of our own in Rust | Not TypeScript; would never agree with the editor |
| Skip the check when Node is missing | A build that passes on one machine and fails on another, and errors that only some people see |
| An opt-out flag or comment | Mik asked for none; a greppable escape hatch can be added later if a real need appears |
Consequences
Building a project now needs Node and pnpm install in the repository, as the language server and the kit's tests already do; CI's Rust job installs them before building the examples. The checker is found next to the CLI's source (packages/checker) or through DUOLITH_CHECKER; a released CLI will need to ship it, which is future work for the toolchain. examples/typed-errors fails on purpose and is left out of CI's clean-build loop.