Registry

A registry is any HTTP endpoint that serves schema-valid JSON - a Next.js public/r folder, a static host, or your own API. The Cubix docs site itself ships the official catalog from public/r.

• Catalog - index.json (or registry.json) lists every item.
• Items - one JSON file per component, for example button.json.
• CLI - cubix add, view, search, and build speak this format.

Catalog schema

The catalog is the registry entry point. Cubix uses https://cubix.design/schema/registry.json:

{
  "$schema": "https://cubix.design/schema/registry.json",
  "name": "cubix",
  "homepage": "https://cubix.design",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "title": "Button",
      "description": "Displays a button or a component that looks like a button.",
      "files": [
        {
          "path": "public/r/button.json",
          "type": "registry:ui"
        }
      ]
    }
  ]
}

Required fields: name, homepage, and items. Each catalog entry points at the published item JSON the CLI will fetch.

Item schema

Each component is a registry item. Schema: https://cubix.design/schema/registry-item.json.

{
  "$schema": "https://cubix.design/schema/registry-item.json",
  "name": "button",
  "type": "registry:ui",
  "title": "Button",
  "description": "Displays a button or a component that looks like a button.",
  "dependencies": ["@base-ui/react"],
  "registryDependencies": [],
  "files": [
    {
      "path": "components/cubix/button.tsx",
      "type": "registry:ui",
      "target": "components/cubix/button.tsx"
    }
  ]
}

When an item needs other Cubix pieces and npm packages, list both:

{
  "$schema": "https://cubix.design/schema/registry-item.json",
  "name": "date-picker",
  "type": "registry:ui",
  "title": "Date Picker",
  "description": "A date picker component with range and presets.",
  "dependencies": ["date-fns", "chrono-node"],
  "registryDependencies": [
    "button",
    "calendar",
    "popover",
    "input",
    "input-group"
  ],
  "files": [
    {
      "path": "components/cubix/date-picker.tsx",
      "type": "registry:ui",
      "target": "components/cubix/date-picker.tsx"
    }
  ]
}

Item types

Cubix primarily ships registry:ui items. The schema also supports related kinds for larger catalogs:

Build and serve

Author a source registry.json, then generate static files with the CLI. Output defaults to public/r:

pnpm dlx cubix@latest build

On Next.js, those files are served as /r/button.json, /r/index.json, and so on. Any host that serves static JSON works the same way. Full build flags are on the CLI page.

Consume a registry

After Installation, add components by name from the configured Cubix registry:

pnpm dlx cubix@latest add button

Or pass a full item URL:

pnpm dlx cubix@latest add https://cubix.design/r/button.json

Inspect before install:

pnpm dlx cubix@latest view button

pnpm dlx cubix@latest search -q "dialog"

Namespaces

Map a short namespace to a URL template in cubix.json. {name} is replaced with the item id:

{
  "registries": {
    "@cubix": "https://cubix.design/r/{name}.json"
  }
}

Custom registries work the same way:

{
  "registries": {
    "@acme": "https://acme.com/r/{name}.json"
  }
}

pnpm dlx cubix@latest add @acme/button

Publish your own

To distribute internal components with the same CLI flow:

1. Keep source under paths your consumers expect (Cubix uses components/cubix).
2. Define a root catalog that conforms to the Cubix registry schema:

{
  "$schema": "https://cubix.design/schema/registry.json",
  "name": "acme",
  "homepage": "https://acme.com",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "title": "Button",
      "description": "A simple button component.",
      "files": [
        {
          "path": "components/cubix/button.tsx",
          "type": "registry:ui"
        }
      ]
    }
  ]
}

3. Run cubix build and deploy the output directory.
4. Share the namespace URL template so teams can cubix add @acme/button.

Authoring guidelines

• Give every item a clear title and description - humans and Skills both rely on them.
• List all npm packages in dependencies and all Cubix peers in registryDependencies.
• Set files[].target to the path consumers should receive after add.
• Keep the visual API aligned across Base UI, React Aria, and Radix when you publish base variants.
• Prefer Cubix tokens only - never ship hardcoded brand colors in registry source.
• Update the catalog whenever you add or rename an item so search stays accurate.

Next: CLI, Skills, or browse Components.