Duolith docs

0097. Pages are checked with the strictest practical TypeScript options

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval as a language change
  • Planning item: none

Context

Mik asked that everything that could fail at run time fail when the app is built instead, so that code feels "hands off and impossible to break". TypeScript's defaults let a lot through: a read from a list by position is typed as if it always succeeds, a key read from a route's query looks like a known field, an optional prop can be passed undefined without saying so, and a switch can miss a case. The editor and duolith check must use one set of options (decision 0096), so the set is part of the language.

Decision

Every page and component is checked with these options (packages/language-server/src/typing.ts, DUOLITH_COMPILER_OPTIONS). A project's own tsconfig.json cannot loosen them.

OptionWhat it catchesCode
strict (all of its parts)null and undefined where a value is needed, implicit any, unchecked this, loose function typesE0343, E0344
noUncheckedIndexedAccessposts[0].caption when the list may be empty; query["tab"] that may be missingE0343
exactOptionalPropertyTypesan optional field set to undefined in a script object where the type did not allow itE0340
noPropertyAccessFromIndexSignaturequery.tab written as if tab were a known fieldE0345
noImplicitReturnsa function that returns a value on some paths and nothing on othersE0346
noFallthroughCasesInSwitcha case that runs into the next oneE0346
noImplicitOverride, useUnknownInCatchVariablesan override written by accident; a caught error used as if its type were knownE0349, E0343
allowUnreachableCode: false, allowUnusedLabels: falsecode that can never run, and labels nothing uses, are errors, not hintsE0346
  • **noUncheckedIndexedAccess: yes.** It is the option that makes "maybe missing" visible everywhere, including the route's query. The cost is a ?., a ?? or a <show when> where a value is read by position. That cost is the point.
  • **exactOptionalPropertyTypes: yes, with one rule in markup.** In markup, undefined given to an attribute or to an optional prop means "left out", as it does at run time (decision 0095). So <Card count={maybe}> is allowed when count is optional, and a script object literal still follows the exact rule.
  • The data layer is typed so that loading and failure must be handled. resource(...).data is T | undefined, so reading it is E0343 until a page handles the missing case with <show when={feed.data}>, ?. or ??. Decision 0098 proposes making a resource's states a union, so a page cannot forget the failed state either.
  • Nothing switches the check off. In a page's script block, in its markup expressions and in the project's own .ts and .d.ts files:
    • E0357: a @ts-nocheck, @ts-ignore or @ts-expect-error comment, in any letter case, where TypeScript honours it (a comment that only mentions one is fine), and a /// <reference> however it is spaced, which adds declarations no import names.
    • E0358, every use of a value typed any, whatever produced it: a library (JSON.parse, Response.json(), Reflect.get), import(path) of a path in a variable, a type alias, a package's declarations. A value typed any may not be read from, called, constructed, extended, used as a key, spread, destructured or iterated over, and may not be assigned, passed, returned, put in an object or a list or given a type with as or satisfies where the type it lands in is not unknown or any (an initialiser, an argument, a return, a prop in markup, a binding; a variable with no type written takes the any, so it counts). A markup expression may not be any, and a value whose type holds an any (Promise<any>, any[]) may not land where that place is typed. This is typescript-eslint's no-unsafe-* rules, built into the type check (packages/language-server/src/any-uses.ts).
    • E0358 also for what a use check cannot see: the any keyword (const u: any, as any); the Function, CallableFunction and NewableFunction types and a call of one (such as the Function that .constructor gives); eval and Function as values, under any name or key (globalThis[key] where key is "eval"), since they run text as code, though typeof eval in a type is only a type; a string given to setTimeout or setInterval, which run it as code; the ! that says a value is there; as unknown as; as never; a cast from unknown to a type parameter (function lie<T>(x: unknown): T { return x as T; }), which gives whatever type the caller picks; and a definite assignment (let x!: T).
    • The fix for an unknown type is unknown, narrowed before use (const data: unknown = JSON.parse(text), then a type guard or a validation function), and for a value that may be missing, handling the missing case. A cast from a value already typed unknown to a type the code names is allowed: it is how data of unknown shape is given a type.
    • The analyzer refuses these from the text, as quick errors; the refusals (packages/language-server/src/refusals.ts), which the build's checker and the editor both run, refuse them again from what TypeScript resolved, so another spelling (globalThis.eval, ///<reference>, an import written as import("…") in a type) cannot get past, and so the editor shows what the build reports. docs/explanation/types.md lists the few errors only the build reports.
    • E0359: declare (const, let, var, function, class, enum, module, global) and namespace, which name what does not exist when the page runs: declare const secret builds, then fails with "secret is not defined".
    • A library's any is no longer allowed to be used (changed while this record is proposed; see below).
  • A tsconfig.json cannot loosen the options, in the editor or the build: each option strict turns on is also set by name, so strictNullChecks: false in a project changes nothing.
  • **The project's own .ts and .d.ts files are checked too.** Each one a page or component imports is in the same program, checked with the same options (so skipLibCheck is off; TypeScript's own lib files are still not checked), and its errors are reported at its own line. No file outside the project's folder may reach the program unless it is a package under node_modules (E0356), however the import is written: a file outside it would be checked and shipped by nothing. A folder named node_modules deeper in the project is the project's own, and checked. Only its types can be imported into a page (import type): the build ships pages, components and public/, not other files, so a value import from a local file is E0356 with that fix, and so is one without an extension, which would otherwise build and fail when the page runs.
  • One split in the kit. ChipGroup's binding took a string or a list of strings depending on multiple, which no type can say. It now has value for one choice and values for several. The examples that bound a list to value now bind values.

Alternatives considered

OptionWhy not
TypeScript's strict aloneLeaves reads by position, index-signature reads, missing returns and fall-through cases unchecked: the errors Mik asked to catch
Let a project's tsconfig.json set the optionsTwo projects would mean different things by the same page, and the editor and the build could disagree
exactOptionalPropertyTypes everywhere, markup included<Card count={maybe}> would need a condition markup cannot write; at run time undefined already means "use the default"
checkJs-style lint rules (unused locals, unused parameters) as errorsUnused names are untidy, not broken; they stay as hints in the editor
Refuse each source of any (eval, Function, a type that resolves to any) and allow a library's ownEach review found a new spelling that produced an unchecked any: a generic alias over typeof JSON.parse, globalThis[k], .constructor.constructor.call, Reflect.get, import(spec). Refusing uses catches all of them, and every later one
Allow a library's any, such as JSON.parse's result, to be usedIt is the same hole by another door: JSON.parse(text).deep.deeper builds and fails when the page runs. The value can always be received as unknown instead, so nothing is lost

Changed while proposed

The first version of this record refused the sources of any it knew and allowed "a library's own any, such as JSON.parse's result", as outside the project. That allowance is removed: every use of a value typed any in a page, a component or the project's own .ts and .d.ts files is E0358, whatever produced it, a library included. A library's any is still received (const data: unknown = JSON.parse(text) is fine); only using it as any is refused. Mik approved this on 17 Nov 2026: a library's any is refused too.

Consequences

Some correct-looking code is now an error until it says what happens in the missing case, and code that used a library's any directly (JSON.parse(text).name, const data = await response.json()) is an error until it receives the value as unknown and narrows it. No kit part, example, template or skill solution did. Ten example pages, one kit test fixture and one kit part were changed to do that (changes/typed-markup.md). New kit parts and examples must check under these options; every_kit_part_type_checks and the language server's examples test enforce it.