Domains: one file says what the API is
A domain file says what one part of your app is about: the shapes of its data, the queries that read it, the commands that change it, who may call each, and what each may fail with. From it the build writes the types, the validators, the writers, the cache keys and a typed client, in TypeScript and in Rust (decision 0164). The format in full is in spec/language/domains; this page is how to use it.
The example is Plaza, a small social app in examples/social: accounts, posts, follows, media, payments, promotions, notifications and moderation, one domain file each.
duolith domains generate examples/social # every build and duolith dev do this first
Write a domain
# domains/notes.domain.yaml
domain: notes
shapes:
Note:
identity: [id] # a shape with an identity is a model
id: id
authorId: id
body: text(1..500)
pinned: flag
queries:
note:
input: { id: id }
returns: Note
allow: public
at: GET /notes/{id}
commands:
pin:
input: { id: id }
returns: Note
allow: signed in
changes: Note # which answers to refresh when it succeeds
Every name is checked. body: txt fails the build with "there is no type or shape called txt" and "Did you mean text?" (E0595). A query with no allow: fails (E0596): nothing is open by accident, so an open one says allow: public. A command with no changes: fails (E0597), so the client always knows what to refresh. duolith explain E0595 explains any of them.
Rules other than public and signed in, and the origin the client sends to, go in duolith.yaml:
domains:
origin: same # or https://api.example.com
rules:
self: { takes: [id] } # allow: self(authorId)
admin: {}
Use it from a page
A page imports types only, so it reads the domains through typedApi with the generated Api:
import { state, typedApi } from "@duolith/client";
import type { Api } from "../generated/domains/client.ts";
const server = typedApi<Api>("");
const note = state.load("note", () => server.get("/notes/{id}", { params: { id: "n1" } }));
note.data is a Note. Rename body to text in the domain file and the page that reads note.data?.body fails the build at that line (spec/conformance/domains-rename).
Outside pages, such as in tests, createClient() from the same file checks every input before it sends it, sends only to the origin in duolith.yaml, gives each failure as a typed value instead of throwing, and after a command tells onChange the keys of the answers it changed:
import { createClient } from "./generated/domains/client.ts";
const plaza = createClient({ onChange: (keys) => refresh(keys) });
const outcome = await plaza.posts.comment({ postId, commentId, authorId, body });
if (!outcome.ok && outcome.failure.code === "blockedByAuthor") showBlocked();
Validators and writers
Each shape gets checkNote(value), which gives the note with its defaults filled in, or every problem with its JSON Pointer and a reason: an unknown field, text over its length, a number out of range, a list over its length, a value of the wrong kind. writeNote(note) writes only the fields the shape names. A field marked secret, such as a password's hash, has no writer at all, and the build refuses any answer that would hold it (E0601). No validator uses eval, new Function or a regular expression, and the Rust ones in generated/domains/rust/ accept and refuse exactly what the TypeScript ones do.
On a 4-core cloud machine with Node 22, checking Plaza's Post takes about 2.8 µs against zod's 7.4 µs, and a page of 100 posts about 164 µs against 421 µs (pnpm bench --only domains-validate).
Bring an API you already have
duolith domains import api/openapi.yaml --out domains
writes a domain file per tag from an OpenAPI description, and lists, per operation, what it could not read: an integer with no minimum, a pattern, a oneOf, a status with no failure name, what a command changes. It guesses none of these, writes no file over one that is there, and refuses a $ref to a URL or to a file it was not given (E0613).
In the editor
The language server answers in domain files: the build's own problems as you type, go to definition from any name (a shape, a field, a rule in duolith.yaml), rename across every domain file, and completion of keys, types, shapes and rules.