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:
- **An effect from
spec/effects/effects.yaml** (camera). Each permission it declares gets its default reason inpermissions.yaml. A reason already there is kept. - A kit part (
Button). The part is copied intocomponents/<Part>.duo, with its imports of sibling parts pointed at@duolith/kit. An existing file is never overwritten. - Anything else is an npm package:
name,name@version,./folderornpm:name.- The package is installed with the project's package manager (npm, pnpm or yarn, chosen from the lockfile;
DUOLITH_NPMoverrides). - It is then scanned as
duolith scanscans it, and its module manifest decides:everywhere: kept;web-only: kept, with a warning;- anything else: refused, and
package.json, the lockfiles andnode_modulesare put back as they were.
- The package is installed with the project's package manager (npm, pnpm or yarn, chosen from the lockfile;
--json prints spec/schemas/cli/add.schema.json. For a package, the manifest is included.
Alternatives considered
| Option | Why not |
|---|---|
Separate add-part, add-effect and install commands | Three 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 warn | The 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 packages | The 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:namealways means the package. crates/cli/src/add.rshas tests for each kind, including a package that is refused and restored.packages/testing/test/cli-json.test.tschecks the JSON.