Skip to content

registry.json

registry.json is a JSON file hosted at a URL. It lists all blocks available in a registry, their metadata, dependencies, and file manifests.

Schema

JSON
{
  "$schema": "https://blockstudio.dev/schema/registry.json",
  "name": "ui",
  "description": "Core UI blocks for Blockstudio projects.",
  "baseUrl": "https://raw.githubusercontent.com/acme/blocks/main/blocks",
  "blocks": [
    {
      "name": "tabs",
      "title": "Tabs",
      "description": "Tabbed content with accessible keyboard navigation.",
      "category": "layout",
      "type": "blockstudio",
      "dependencies": ["tab-item"],
      "files": [
        "block.json",
        "index.php",
        "style.scss"
      ]
    }
  ]
}

Top-level fields

name

Required. The registry identifier. The CLI validates it but does not display it: commands and output use the key the consumer chose for the registry in blocks.json.

description

Optional. A short description of what this registry contains.

baseUrl

Required. The base URL for downloading block files. Must be a valid URL.

Files are fetched by combining the base URL, the block name, and the file path: {baseUrl}/{block.name}/{file}.

For example, with baseUrl set to https://raw.githubusercontent.com/acme/blocks/main/blocks and a block named tabs with file index.php, the CLI fetches:

Code
https://raw.githubusercontent.com/acme/blocks/main/blocks/tabs/index.php

Block fields

name

Required. The block’s folder name. This is the identifier used in CLI commands and becomes the folder name on disk.

title

Optional. Human-readable name shown in list and search output.

description

Optional. One-line description shown in search results.

category

Optional. Grouping label for list output.

type

Optional. One of blockstudio, create-block, or wordpress.

This is informational only. The CLI does not change behavior based on the block type. It always downloads and copies the files listed in files.

dependencies

Optional. An array of other block names in the same registry that must be installed alongside this block.

When a user adds a block with dependencies, the CLI resolves the full dependency tree and installs everything in the correct order. Circular dependencies are detected and rejected.

Dependencies must exist in the same registry. Cross-registry dependencies are not supported.

files

Required. An array of file paths relative to the block folder. At least one file is required.

These are the exact files the CLI downloads and writes to disk. The paths can include subdirectories:

JSON
{
  "files": [
    "block.json",
    "index.php",
    "style.scss",
    "src/components/tabs.tsx",
    "src/styles/tabs.css"
  ]
}

File resolution

For each file in a block’s manifest, the CLI constructs a download URL:

Code
{baseUrl}/{block.name}/{file}

And writes it to:

Code
{directory}/{block.name}/{file}

The directory structure inside the block folder is preserved. If a file path contains subdirectories, they are created automatically.

Files are always fetched from the baseUrl inside registry.json, not from a location relative to the registry URL in blocks.json.

Validation

The CLI validates registry.json against a Zod schema on every fetch. Invalid registries produce clear error messages with the specific fields that failed validation.

Required fields that are missing, empty blocks or files arrays, invalid URLs, and unknown type values are all caught before any files are downloaded.