Skip to content

Commit 29efd5d

Browse files
docs(registry): document installer metadata (#3658)
Co-authored-by: Kiyeon Jeon <[email protected]>
1 parent d2741b3 commit 29efd5d

2 files changed

Lines changed: 28 additions & 0 deletions

File tree

‎docs/contributing/catalog.mdx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,28 @@ Other useful optional fields include `author`, `authorUrl`, `relatedSkill`,
8686
current authority. The published JSON schema validates the shared manifest
8787
fields but does not yet describe the block-only `params` field.
8888

89+
### Installer metadata
90+
91+
Use `registryDependencies` to name registry items that must be installed first.
92+
The installer resolves dependencies transitively and rejects missing items or
93+
cycles. Reference exact item names and keep the dependency graph small.
94+
95+
Set `minCliVersion` to the first CLI version that supports the item. All resolved
96+
items, including dependencies, must pass the compatibility check before any item
97+
files are installed. An incompatible CLI reports the required version and an
98+
upgrade command.
99+
100+
Set `deprecated` to a short migration message when an item has a replacement.
101+
The installer warns and keeps the item available for existing projects.
102+
103+
```json
104+
{
105+
"minCliVersion": "0.6.96",
106+
"registryDependencies": ["grain-overlay"],
107+
"deprecated": "Use my-block-v2 instead."
108+
}
109+
```
110+
89111
## Build for reuse
90112

91113
Every registry item must:

‎docs/packages/cli.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,12 @@ you a clear error pointing at `init --example`.
153153
pull from and where files land. If it is missing but the directory has an
154154
`index.html`, a default one is written on first use.
155155

156+
When an item declares `registryDependencies`, `add` installs its dependencies
157+
first, resolving them transitively. Before installing any item files, it checks
158+
`minCliVersion` on every resolved item and reports upgrade guidance for an
159+
incompatible CLI. A `deprecated` message produces a warning without blocking
160+
installation.
161+
156162
### `catalog`
157163

158164
Browse the registry.

0 commit comments

Comments
 (0)