Installation

Initialize the project

Run the stable moving tag from an existing Mado application. The CLI validates the installed Mado range, detects the official default or modular source layout, and creates the human-owned mado-ui.json.

npx @madojs/ui@latest init

Use --components, --styles or --templates when the detected paths do not match the application. Commit the configuration file.

Inspect, then copy

Registry discovery does not mutate the project. Inspect available source first, then add one or more items; required dependencies are resolved in the same atomic plan.

npx @madojs/ui@latest list
npx @madojs/ui@latest view button
npx @madojs/ui@latest add button

add never rewrites an existing target by default. Use --dry-run to review writes. An explicit --overwrite is a deliberate reset of directly selected items, not an automatic upgrade policy.

Import owned source

Import the copied theme and CSS recipes once from the application entry, and import autonomous component modules where their custom elements are used. The exact paths come from mado-ui.json.

import "./styles/mado-ui-theme.css";
import "./styles/mado-ui-button.css";

There is no browser import from @madojs/ui. The package is a development CLI and versioned registry; every installed file belongs to the application and can be edited normally.

Keep the lock

Successful writes update .mado-ui.lock.json with the exact registry version, compatibility generation, source paths and normalized SHA-256 hashes. Commit it with the copied source so future diff, update and doctor can distinguish pristine, customized and upstream-changed files.

Normal work continues to use @latest, even years later. An exact npm version is only for reproducing an old installation or a future immutable catalog page.