Duolith docs

0145. An installed Duolith carries its Node companions, and the templates carry tests

  • Status: Accepted (Mik, 16 Nov 2026)
  • Date: 2026-11-14
  • Decided by: wave 5 developer tools agent (domain F), pending Mik
  • Planning item: v1 gap audit, developer tools: "an installed CLI works outside the repository"

Context

duolith check, duolith test and duolith create each run a Node program: the type checker (packages/checker), the test runner (packages/testing) and the scaffolder (packages/create). Until now the CLI found them only in the repository (packages/<name>/src). A duolith copied anywhere else could build, but could not check types, test or make an app.

Decision

  • Where the CLI finds a companion (crates/cli/src/companions.rs), first match wins: When none is found, the error names every folder it looked in (E0351 for the checker).
    1. The environment variable DUOLITH_CHECKER, DUOLITH_TESTING or DUOLITH_CREATE.
    2. The project's node_modules/@duolith/<name>, in the project or a folder above it.
    3. <prefix>/lib/duolith/<name> beside an installed <prefix>/bin/duolith, or lib/duolith/<name> in the binary's own folder.
    4. The repository's packages/<name>, only when the binary or the project is inside the repository, and always from source, so a stale bundle never answers there.
  • Each companion ships as a bundle. scripts/bundle.ts writes dist/bundle/: crates/cli/install/stage.ts --binary <duolith> --out <prefix> lays out an install: bin/duolith and lib/duolith/{checker,testing,create}.
    • the checker: one ESM file, TypeScript's library files, and the declarations it checks against;
    • the testing runner: the package transpiled file by file, with Playwright and spec/effects/effects.yaml;
    • the scaffolder: main.mjs, its templates, and beside them the files every app gets (skills/app, llms.txt, llms/; since decision 0160 the skills are Duolith's packs, carried by the compiler, and skills/app is no longer shipped), laid out as the npm package lays them out.
  • The create templates:
    • Existing: blank, tabs and data.
    • New: tabs-auth, effects, native (with a commented app: manifest stub in duolith.yaml), themed and tested.
    • Every new template carries theme.yaml, duolith.yaml and at least one *.test.ts.
    • Tests check that each one builds, lints clean with --deny-warnings, is formatted, and passes its own tests; native also builds for native.
  • **The testing origin is https://duolith.test.** Sign-in and secure storage need WebCrypto, which only a secure context has.

Alternatives considered

OptionWhy not
Compile the companions into the binary (embedded JavaScript)Still needs Node to run them. The binary grows by the TypeScript compiler and Playwright, and updating one means a new binary.
Require npm install @duolith/checker @duolith/testing in every projectIt would be one resolution step among several, as it is now (2), but making it the only one breaks duolith create and a first duolith check on a fresh machine.
Look only beside the binaryIt ignores a project that pins its own companion versions.

Consequences

  • crates/cli/tests/installed_cli.rs stages an install in a temporary folder outside the repository. It makes an app from a template, checks, builds and tests it, then builds and tests a copy of examples/control-flow. It reports E0340 in a copy of typed-errors, and E0351 once the checker is removed.
  • The release (domain G) must run each package's bundle script and stage the layout above into every CLI archive. @duolith/checker, @duolith/testing and @duolith/create are publishable from their dist/bundle/, but are still private: true.
  • Node 22 or later is required on the machine for check, test and create, as before.