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.

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.

Update the Cadence UI checkout to the new reviewed commit or tag.
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

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

3.5 KiB Raw Blame History