128 lines
3.7 KiB
Markdown
128 lines
3.7 KiB
Markdown
# 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:
|
|
|
|
```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`.
|
|
|
|
To validate the end-to-end 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.
|
|
|
|
## 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:
|
|
|
|
```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
|
|
|
|
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
|