Registry format

This is a published format. facet add consumes it, forks emit it, and changing it incompatibly means bumping RegistryIndex.version.

What a registry serves

<base>/index.json      the index the CLI reads first
<base>/<name>.json     one payload per item, source text inlined

Plus, at the site root rather than under the registry base, two generated files:

Both are generated by the deploy that publishes the registry rather than committed, so neither can lag the CLI that writes files pointing at them.

The CLI reads index.json first, and item payloads lazily for what is being added, removed or diffed. Remote reads send accept: application/json and time out after 15 seconds.

Revisions

The published registry is served twice — once at a path that moves, and once per push at a path that never will:

r/index.json          the moving registry every CLI reads by default
r/button.json
r/a1b2c3d/index.json  the same bytes, frozen, forever
r/a1b2c3d/button.json

A revision is keyed by the commit SHA that produced it. That is the only identifier already immutable, unique per publish, and meaningful outside the registry. A CLI version would not work. Three components shipped under 0.3.0 on separate pushes, because a component reaches users by being published rather than by a CLI release.

The two copies are byte-for-byte identical rather than re-rendered, and a test asserts they match.

revisions.json at the site root lists what exists, newest first:

{
  "latest": "d345608",
  "revisions": [
    { "revision": "d345608", "generatedBy": "0.4.0", "components": 23 },
    { "revision": "821604a", "generatedBy": "0.3.1", "components": 10 }
  ]
}

It is rebuilt by scanning the published tree rather than appended to, so it cannot claim a revision that is not there.

To read from one, point at it as a base — see pinning a revision.

index.json

{
  "version": 1,
  "generatedBy": "0.4.0",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "description": "Button with variant and size recipes",
      "files": ["ui/button.tsx"],
      "registryDependencies": ["utils", "text"],
      "dependencies": [
        "@facet-ui/react-variants@^0.1.1",
        "@lattice-ui/react-runtime@^0.8.0"
      ],
      "tokens": ["primary", "primary-foreground", "…"]
    }
  ]
}

Item fields

providers

It exists because one failure in the registry is not a build failure.

{
  "name": "dialog",
  "providers": [
    {
      "name": "PortalProvider",
      "package": "@lattice-ui/react-layer",
      "props": { "container": "player-gui" },
      "reason": "Lattice reads the portal target from it, and throws when a dialog opens without one"
    }
  ]
}

facet add offers to write it into the client entry, and facet doctor reports when it is gone.

The registry declares it, not the CLI. The alternative was for the CLI to know that dialog needs PortalProvider. That would put the knowledge in a released binary. The next layered component would then need a CLI release to be wired correctly.

version did not move for it. loadIndex rejects an index whose version it does not recognise. Bumping to 2 would break every installed CLI to deliver a field those CLIs would ignore. An optional field is compatible both ways. The number is for removing a field, renaming one, or changing what an existing one means.

Item types and where they land

Item payloads

<name>.json is the index entry with the file list expanded from strings into objects carrying the source text:

{
  "name": "utils",
  "type": "registry:lib",
  "files": [
    {
      "path": "lib/utils.ts",
      "type": "registry:lib",
      "content": "export { type ClassValue as ClassName, cn } from \"@facet-ui/react-variants\";\n…"
    }
  ],
  "dependencies": ["@facet-ui/react-variants@^0.1.1"]
}

A path’s first segment is the alias and the rest is kept, so a multi-file block stays a directory.

What ~/ means in the content

Registry sources address each other with a ~/ prefix, and the first segment is an alias name:

import { TextSlot } from "~/lib/text";
import { cn } from "~/lib/utils";

facet add rewrites these for the consumer’s project. Textually when the alias has an import specifier, and otherwise as a relative path from where the importing file lands. An unknown alias segment is left alone, so it fails loudly at typecheck rather than being rewritten to something wrong.

Relative paths in registry source are a bug. The CLI can rewrite ~/lib/utils. It cannot rewrite ../lib/utils.

What a component may import

Anything else will not resolve once copied:

• @rbxts/*
• @lattice-ui/*
• @facet-ui/react-variants
• ~/…

Validation rules

validateRegistry() runs in registry:check, so a broken registry fails CI rather than facet add:

That last one is the non-obvious one. facet add unions dependency strings across the install set. @lattice-ui/react-runtime in one item and @lattice-ui/react-runtime@^0.8.0 in another survive as two entries, and both reach the package manager. A dependency carries a floor when the source needs behaviour a specific version introduced, and then the same package carries the same spec everywhere.

What validation cannot catch is a missing npm dependency — an import the entry never declared. That ships a file that cannot compile in a project without the package.

Specs

Dependency strings are name or name@range, split on the last @ so a scoped package’s leading one survives. @facet-ui/theme is a name, and vela-rbxts@^0.9.0 is a name and a range.

Range comparison is deliberately not a semver implementation. It answers one question for the shapes Facet writes, ^0.9.0, >=0.8.0 and 0.1.1. Is what is installed at least the version this needs? Anything else is reported as unverifiable rather than guessed at.

Errors