kurihada
c177fbefa4
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
156 lines
4.9 KiB
Markdown
156 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
pnpm registry:build
|
|
```
|
|
|
|
To verify that the generated file is current:
|
|
|
|
```bash
|
|
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 source-copy consumer flow locally:
|
|
|
|
```bash
|
|
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.
|
|
|
|
For the broader release path, the canonical release gate also includes registry validation and
|
|
both consumer smoke suites:
|
|
|
|
```bash
|
|
pnpm harness:validate:release
|
|
```
|
|
|
|
Use that gate before release work that changes package, docs, or consumer-facing behavior.
|
|
|
|
## 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](/Users/xd/project/cadence-ui/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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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
|