Duolith docs

Making an app, adding to it, and installing Duolith

duolith create

duolith create my-app                       # the blank template
duolith create my-app --template tabs-auth  # into ./my-app
duolith create my-app --into ~/code --json  # spec/schemas/cli/create.schema.json
TemplateHolds
blankOne screen
tabsTabs in a root layout
dataState that loads (state.load) and an action
tabs-authTabs with an account behind sign-in: a sign-in screen, an account screen that signs out, and tests that sign in with the mock sign-in backend
effectsThe camera (after asking permission), haptics, storage and share on one screen, tested with the effects mocked
nativeReady for duolith build --target native, with a commented app: manifest stub in duolith.yaml to fill in
themedA theme.yaml with its own brand colour, used through the kit's parts
testedA page and a component, each with its tests

Every app gets AGENTS.md, CLAUDE.md and the llms/ reference; the skills come from Duolith's packs (duolith packs, packs.md). Each template after data also has theme.yaml, duolith.yaml and at least one *.test.ts. They are checked to build, to pass duolith lint --deny-warnings and duolith fmt --check, and to pass their own tests. An app's name is lower-case letters, digits and hyphens, starting with a letter. A folder already in use is refused.

duolith add

duolith add <name> [project] adds one of three things, chosen by the name (decision 0146):

duolith add camera            # an effect: its usage description goes in permissions.yaml
duolith add Button            # a kit part: copied into components/Button.duo to change
duolith add date-fns          # an npm package: installed, scanned, and kept only if it can ship
duolith add ./vendor/my-lib   # a package from a folder; npm:name forces the npm meaning
  • An effect. Each permission the effect needs gets its default reason in permissions.yaml. Edit the reason to say why your app asks. A reason already there is kept.
  • A kit part. The part is copied with its imports of other parts pointed at @duolith/kit. An existing file is never overwritten.
  • A package. It is installed with the project's package manager (from its lockfile, or DUOLITH_NPM), then scanned as duolith scan scans it.
    • A package that runs everywhere is kept.
    • A web-only one is kept, with a warning.
    • Anything else is taken out again, and package.json, the lockfile and node_modules are put back as they were.

Installing Duolith

An installed Duolith is one folder:

<prefix>/bin/duolith               the compiler and command line
<prefix>/lib/duolith/checker/      duolith check's type checker
<prefix>/lib/duolith/testing/      duolith test's runner, with Playwright
<prefix>/lib/duolith/create/       duolith create's templates and reference

Only Node 22 or later is needed beside it, for check, test and create. node crates/cli/install/stage.ts --binary <duolith> --out <prefix> makes the folder from a build.

Each companion is looked for, in this order:

  1. The environment variable: DUOLITH_CHECKER, DUOLITH_TESTING or DUOLITH_CREATE.
  2. The project's own node_modules/@duolith/<name>.
  3. lib/duolith/<name> beside the binary.
  4. Inside this repository, packages/<name>.

When none is found, the error lists every folder looked in (decision 0145). crates/cli/tests/installed_cli.rs stages an install outside the repository, then makes, checks, builds and tests an app there.

duo, a shorter name

The command is duolith, and that is what the docs, error messages and generated files say. If you would rather type duo, add an alias yourself (decision 0161):

alias duo=duolith                                   # bash and zsh: in ~/.bashrc or ~/.zshrc
alias duo duolith                                   # fish: then `funcsave duo`
Set-Alias duo duolith                               # PowerShell: in $PROFILE

Duolith does not install duo itself, because GitLab's Duo CLI installs a command of that name. Check with command -v duo before adding the alias; an alias takes the place of that command in your shell.