Types
A page is checked by TypeScript, the script block and the markup together. If a value has the wrong type anywhere, the app does not build, and the editor shows the same error where it is written (a few checks of the whole project, such as links to pages, show only in the build: see what the editor shows). There is nothing new to learn: the types are TypeScript's, and the markup uses the types the script gives it.
What is checked
Everything that has a type:
- Text.
{post.caption}must be a string or a number. A boolean or an object would show as "false" or "[object Object]", so it is an error. - Attributes. Each attribute takes a type:
disabledtakestrueorfalse,srca string, a slider'svaluea number. An attribute that takes a set of words checks the word you write, so<input type="emial">is an error. A quoted number must be a number (rows="3", notrows="many"), and a true-or-false attribute is never quoted:disabled="false"would turn it on, so writedisabled={false}, ordisabledalone for true. - **Your own
.tsfiles.** A.tsfile a page imports is checked with the page, and its errors show in that file. Import only its types (import type { Recipe } from "../lib/recipe.ts"): the built app does not include other files, so a value from one is an error. Put shared code in a component, or in the script block. - Events. A handler gets what its event gives.
on:input={(event) => (draft = event.value)}knowsevent.valueis a string. - Bindings.
bind:valuechecks both directions: a slider's state must hold a number, an input's a string. - Props. A component's props are the type in its
props<...>(), and the kit's parts are typed the same way.<Card title={42}>is an error whentitleis a string. - Routes. On
pages/post/[id].duo,route()has anidthat is a string. - Links and images.
href="/settings"must name a page, andsrc="/images/lake.svg"a file inpublic/.
Handle the missing case
Many errors say a value "is possibly undefined" (E0343). They are the ones that would break the page when it runs: data that has not loaded yet, a user who is not signed in, the first item of a list that may be empty. Say what happens then:
<show when={feed.data}>
<list each={feed.data} as="post" key={post.id}>
<text>{post.caption}</text>
</list>
</show>
<otherwise>
<text>Loading…</text>
</otherwise>
Inside <show when={feed.data}>, feed.data is known to be there. In the script, use ?. and ??: posts[0]?.caption ?? "No posts yet".
A route's query has keys nobody declared, so read them with brackets and a fallback: query["next"] ?? "/" (E0345 explains why).
Handle every case
A function that switches over a union must handle each member, or end with a return (E0346):
type Tone = "info" | "success" | "danger";
function icon(tone: Tone): string {
switch (tone) {
case "info":
return "info";
case "success":
return "check";
case "danger":
return "alert";
}
}
Add a fourth tone and this function stops building until it handles it.
In markup, <match> does the same (decision 0098): each <case is="word"> shows its children when the value is that word, and a member with no case fails the build (E0500). A case the union does not have is E0501. End with <case else> to show something for every other value instead. A <match> works on a union of words (string literals) only: over a union of numbers or booleans, such as 1 | 2 or boolean, each case's is is text, so every case is E0501 and every member E0500; compare with <show when={...}> there instead. The check trusts the value's type: a cast such as value={tone as "info"} tells it the value can only be info, so a match with only an info case builds, and the members the cast left out are never checked. Leave casts out of a match's value.
<match value={tone}>
<case is="info"><icon name="info" /></case>
<case is="success"><icon name="check" /></case>
<case is="danger"><icon name="alert" /></case>
</match>
Matching on a field narrows what holds it, so <match value={feed.state.status}>'s ready case may read feed.state.data (see data). A match holds only cases (E0502), a case only appears in a match (E0503), each case has is or else (E0504), no word appears twice (E0505), and else comes last (E0506).
Data of unknown shape
A value typed any is never checked, so using one is an error (E0358), wherever it came from: JSON.parse, response.json(), a library. Receive it as unknown instead, and check its shape before you use it:
type Saved = { name: string };
function isSaved(value: unknown): value is Saved {
return typeof value === "object" && value !== null && "name" in value && typeof value.name === "string";
}
const data: unknown = JSON.parse(localStorage.getItem("saved") ?? "null");
const name = isSaved(data) ? data.name : "Guest";
const data = JSON.parse(text), JSON.parse(text).name and <text>{JSON.parse(text)}</text> are each E0358; const data: unknown = JSON.parse(text) is fine.
Passing "maybe"
Giving an attribute or an optional prop undefined is the same as leaving it out: the attribute is not set, and the prop takes its default. So <Card count={maybeCount}> is fine when count is optional.
Running the check
duolith check runs every check duolith build does and writes nothing. duolith build and duolith dev run it too, and duolith dev shows a type error in the browser and the terminal like any other error. There is no way to turn it off: // @ts-ignore, // @ts-nocheck and // @ts-expect-error are errors in any letter case, and so are any and any use of a value typed any, Function, eval, text given to setTimeout, ! ("it is there"), as unknown as, as never and declare, however they are spelt. For a value whose type is not known yet, write unknown and check it before use; for a value that may be missing, say what happens then.
$ duolith check examples/minimal
1 page file(s) checked: no errors
The check runs TypeScript in Node.js, so it needs Node 22.18 or later and Duolith's type checker, which an installed Duolith carries in its lib/duolith folder (duolith explain E0351 says where it is looked for). examples/typed-errors is a page full of mistakes, to see what each error looks like. duolith explain E0343 explains any code.
How it works, and the full list of what is and is not caught: docs/explanation/types.md.