Duolith docs

Lint

duolith lint gives advice on a project that builds: things that are not errors, but are likely to hurt the people using the app or the people writing it. Editors show the same warnings as you type, with a quick fix where there is one.

duolith lint                    # the project in this folder
duolith lint examples/social    # another project
duolith lint --fix              # apply every safe fix, then report what is left
duolith lint --json             # { ok, fixed, notApplied, diagnostics: [{ file, line, column, code, severity, message, help, fix }] }
duolith lint --deny-warnings    # fail on warnings too, as CI does

It exits 1 when a rule set to error finds something (or any warning, with --deny-warnings), and when the project does not build.

--fix changes nothing on screen. It fixes a copy of the project first, formats each fixed file that was formatted before, and writes your files only once the copy builds; a fix that would break the build is left out and named. Fixes marked editor below are offered only as a quick fix in the editor, because they change how the screen looks.

The rules

CodeRuleFindsFix
W0001press-without-roleA <view> with on:press and no role or tab-stop: a keyboard cannot reach itEditor: makes it a <button>, which centres its content
W0002field-without-labelAn input, textarea, slider, toggle or checkbox without label or labelled-byLabels it after its placeholder
W0003low-contrastText whose text- and bg- tokens are below WCAG 2.1 contrast (4.5:1, large text 3:1, counting font- weights) in a colour scheme the app shows. A colour set by a style block, behind a prefix such as dark: or by class:bg-... is not guessed at
W0004nested-pressableA button, link or on:press element inside another one
W0020list-without-keyA <list> of more than one item without key; not one of fixed values, written out or named by a const
W0021large-inline-literalAn array or object of 160 characters or more in a markup expression that runs again (it reads a let of the script, or is in a list); not in a handler such as on:press={() => ...}
W0022effect-writes-what-it-readsAn effect that reads and assigns the same state; not inside a function it makes, such as a setInterval callback
W0040unused-stateState or a derived value nothing uses; shared state is used by other screensRemoves the declaration, unless it calls something, or has new or await
W0041unused-propA prop the component never uses
W0042unreachable-otherwiseAn <otherwise> after <show when={true}>Removes the otherwise and its line, keeping comments before it
W0043shadowed-nameA list's as or index that hides a name the script declares
W0060conflicting-utilitiesA utility a later one in the same class overrides completely, such as p-2 in p-2 p-4Removes it
W0061hard-coded-colourA hex colour in a style block's values or an image placeholder that a theme token has in the light scheme (not in selectors, comments or strings)Writes the token, when only one token has that value

duolith explain W0020 or duolith explain list-without-key prints a rule's explanation. examples/lint-showcase trips every rule once.

Setting rules

A project sets rules in duolith.yaml at its root, beside theme.yaml, by name or code:

lint:
  list-without-key: error   # duolith lint fails, editors show an error
  large-inline-literal: off # the rule does not run
  W0061: warning            # the default

A misspelt rule name is reported with the closest one, and a code must be written as the catalogue writes it (W0061, not w0061). Setting one rule by both its name and its code is warned about; the later entry wins. A duolith.yaml that cannot be read or is not UTF-8 text stops duolith lint; editors show the problem at the top of each page (W0099). The file is described by spec/schemas/project.schema.json. Decision 0080 has the reasons.