cadence-ui/docs/registry.md

Registry Install and Upgrade

Cadence UI now supports a minimal internal registry flow for source-owned consumers. The goal is not package publishing yet. The goal is to make one reviewed repo state directly consumable by another app.

What the registry contains

• registry/config.json: the authored registry format
• registry/index.json: generated install metadata
• scripts/build-registry.mjs: rebuilds and validates the generated index
• scripts/registry-install.mjs: copies selected source files into a consumer project

registry/index.json is intentionally machine-readable. It records:

• installable item names
• entrypoints and copied files
• transitive source files required by each item
• external package dependencies
• the package versions that produced the registry snapshot

Maintainer workflow

Whenever packages/ui or packages/tokens changes in a way that affects installable source, refresh the registry metadata:

pnpm registry:build

To verify that the generated file is current:

pnpm registry:check

The pull request workflow now runs pnpm registry:check, and the release version PR workflow refreshes the registry automatically via pnpm release:version.

To validate the end-to-end consumer flow locally:

pnpm test:registry:consumer

That smoke test creates a temporary app, runs the registry installer, installs the required dependencies, and verifies that the copied source both typechecks and builds.

Consumer install flow

1. Pin the Cadence UI source

Consumers should install from a reviewed Cadence UI repo state, usually:

• the merge commit of a version PR, or
• a maintainer-created tag that points at that versioned commit

The consumer does not need this repo as a runtime dependency. It only needs access to the checked-out source when running the installer.

2. Run the installer from the Cadence UI repo

From this repository checkout:

pnpm registry:install --project ../acme-app button dialog

The installer will:

• include tokens automatically when a component requires it
• copy files into src/cadence-ui
• preserve shared internal imports under src/cadence-ui/components, src/cadence-ui/lib, and src/cadence-ui/tokens
• add any missing runtime dependencies to the consumer's package.json
• write src/cadence-ui/.install-manifest.json

Useful flags:

• --target-dir src/shared/cadence-ui: customize the destination root
• --skip-package-json: copy files without editing the consumer package manifest
• --dry-run: preview copied files and package changes

Consumer upgrade flow

Upgrades stay source-owned. There is no generated wrapper or hidden runtime.

1. Update the Cadence UI checkout to the new reviewed commit or tag.
2. Re-run the installer against the same consumer project.

pnpm registry:install --project ../acme-app

If no item names are provided, the installer reuses the list stored in src/cadence-ui/.install-manifest.json.

After that:

• review the consumer diff
• run the consumer package manager install if package.json changed
• verify imports still point at src/cadence-ui/tokens/styles.css

Expected consumer import points

At minimum, the consumer app should import:

• src/cadence-ui/tokens/styles.css from its global app stylesheet or entry module

For package consumers instead of source-copy installs, the equivalent convenience import is:

• @ai-ui/ui/styles.css

If the consumer wants the theme helpers, they can also import from:

• src/cadence-ui/tokens/index.ts

Current scope

This registry flow is intentionally minimal:

• it copies source files
• it writes dependency intent into the consumer app
• it supports reinstalling the same item set for upgrades

It does not yet:

• publish to npm
• host a remote registry API
• auto-tag or auto-publish releases
• resolve consumer-specific codemods during upgrade