cadence-ui/docs/registry.md

Registry Install and Upgrade

Cadence UI supports a source-copy registry flow for teams that want local ownership of component source inside their own application.

This is the optional customization path. The default downstream consumption model is now package install via @ai-ui/ui, with @ai-ui/tokens available for lower-level token imports.

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.

The generated index includes transitive local helpers, not just component entrypoints. If a component starts importing a shared file such as packages/ui/src/lib/icons.tsx, rebuild the index before merge so source-copy consumers receive the full dependency graph.

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

Choose this flow when:

• your team wants to edit copied component code locally
• you expect app-specific divergence that would be awkward to upstream immediately
• you prefer source ownership over centralized package upgrades

If you just want to use Cadence UI in another app with the lowest maintenance overhead, use the package flow in docs/releasing.md instead.

1. Pin the Cadence UI source

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

• the cadence-ui-vX.Y.Z tag created for the release, or
• the matching merge commit if the source-copy install must be tested before the tag is created

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:

• host a remote registry API
• resolve consumer-specific codemods during upgrade