Duolith docs

0146. duolith add decides what to add by what the name is, and keeps a package only when it can ship

  • 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: "duolith add <module|part|effect> consuming the module manifest"

Context

There are three kinds of thing an app adds:

  • a platform effect, which needs its usage description in permissions.yaml;
  • a kit part, copied in so the app can change it;
  • an npm package, which may not run on every target (decision 0073).

One command for all three is easier to remember than three.

Decision

duolith add <name> [project] [--json] looks at the name:

  1. **An effect from spec/effects/effects.yaml** (camera). Each permission it declares gets its default reason in permissions.yaml. A reason already there is kept.
  2. A kit part (Button). The part is copied into components/<Part>.duo, with its imports of sibling parts pointed at @duolith/kit. An existing file is never overwritten.
  3. Anything else is an npm package: name, name@version, ./folder or npm:name.
    • The package is installed with the project's package manager (npm, pnpm or yarn, chosen from the lockfile; DUOLITH_NPM overrides).
    • It is then scanned as duolith scan scans it, and its module manifest decides:
      • everywhere: kept;
      • web-only: kept, with a warning;
      • anything else: refused, and package.json, the lockfiles and node_modules are put back as they were.

--json prints spec/schemas/cli/add.schema.json. For a package, the manifest is included.

Alternatives considered

OptionWhy not
Separate add-part, add-effect and install commandsThree names to learn for one intent. Effect, part and package names do not collide today (effects are camelCase words, parts PascalCase, packages lower case with dashes or a scope).
Keep a refused package and only warnThe rule is that what cannot ship fails loudly. A package that runs on no target would fail every build later, far from the cause.
Refuse web-only packagesThe web build can use them. The warning says that iOS and Android cannot.

Consequences

  • If an effect, a kit part and a package ever share a name, the order above decides. npm:name always means the package.
  • crates/cli/src/add.rs has tests for each kind, including a package that is refused and restored. packages/testing/test/cli-json.test.ts checks the JSON.