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
| Template | Holds |
|---|---|
blank | One screen |
tabs | Tabs in a root layout |
data | State that loads (state.load) and an action |
tabs-auth | Tabs 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 |
effects | The camera (after asking permission), haptics, storage and share on one screen, tested with the effects mocked |
native | Ready for duolith build --target native, with a commented app: manifest stub in duolith.yaml to fill in |
themed | A theme.yaml with its own brand colour, used through the kit's parts |
tested | A 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 asduolith scanscans 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 andnode_modulesare 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:
- The environment variable:
DUOLITH_CHECKER,DUOLITH_TESTINGorDUOLITH_CREATE. - The project's own
node_modules/@duolith/<name>. lib/duolith/<name>beside the binary.- 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.