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.
| Option | What it catches | Code |
|---|---|---|
strict (all of its parts) | null and undefined where a value is needed, implicit any, unchecked this, loose function types | E0343, E0344 |
noUncheckedIndexedAccess | posts[0].caption when the list may be empty; query["tab"] that may be missing | E0343 |
exactOptionalPropertyTypes | an optional field set to undefined in a script object where the type did not allow it | E0340 |
noPropertyAccessFromIndexSignature | query.tab written as if tab were a known field | E0345 |
noImplicitReturns | a function that returns a value on some paths and nothing on others | E0346 |
noFallthroughCasesInSwitch | a case that runs into the next one | E0346 |
noImplicitOverride, useUnknownInCatchVariables | an override written by accident; a caught error used as if its type were known | E0349, E0343 |
allowUnreachableCode: false, allowUnusedLabels: false | code that can never run, and labels nothing uses, are errors, not hints | E0346 |
- **
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,undefinedgiven 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 whencountis 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(...).dataisT | 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
.tsand.d.tsfiles:- E0357: a
@ts-nocheck,@ts-ignoreor@ts-expect-errorcomment, 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 typedanymay 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 withasorsatisfieswhere the type it lands in is notunknownorany(an initialiser, an argument, a return, a prop in markup, a binding; a variable with no type written takes theany, so it counts). A markup expression may not beany, and a value whose type holds anany(Promise<any>,any[]) may not land where that place is typed. This is typescript-eslint'sno-unsafe-*rules, built into the type check (packages/language-server/src/any-uses.ts). - E0358 also for what a use check cannot see: the
anykeyword (const u: any,as any); theFunction,CallableFunctionandNewableFunctiontypes and a call of one (such as theFunctionthat.constructorgives);evalandFunctionas values, under any name or key (globalThis[key]wherekeyis"eval"), since they run text as code, thoughtypeof evalin a type is only a type; a string given tosetTimeoutorsetInterval, which run it as code; the!that says a value is there;as unknown as;as never; a cast fromunknownto 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 typedunknownto 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 asimport("…")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) andnamespace, which name what does not exist when the page runs:declare const secretbuilds, then fails with "secret is not defined". - A library's
anyis no longer allowed to be used (changed while this record is proposed; see below).
- E0357: a
- A tsconfig.json cannot loosen the options, in the editor or the build: each option
strictturns on is also set by name, sostrictNullChecks: falsein a project changes nothing. - **The project's own
.tsand.d.tsfiles are checked too.** Each one a page or component imports is in the same program, checked with the same options (soskipLibCheckis 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 undernode_modules(E0356), however the import is written: a file outside it would be checked and shipped by nothing. A folder namednode_modulesdeeper 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 andpublic/, 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 hasvaluefor one choice andvaluesfor several. The examples that bound a list tovaluenow bindvalues.
Alternatives considered
| Option | Why not |
|---|---|
TypeScript's strict alone | Leaves 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 options | Two 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 errors | Unused 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 own | Each 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 used | It 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.