Skip to content

blocks.json

blocks.json lives in the root of your theme or plugin. It tells the CLI where to install blocks and which registries to search.

Schema

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}

Fields

$schema

Optional. Points to the JSON Schema for editor autocomplete and validation.

directory

Required. Relative path from blocks.json where blocks are installed.

Each block gets its own subfolder inside this directory. If directory is blockstudio and you add hero, the files land in blockstudio/hero/.

registries

Required. An object mapping namespace names to registry references.

The key is the namespace used in CLI commands (npx blockstudio add ui/hero). The value is either a URL string or an object with url and optional headers.

String format (public registries):

JSON
{
  "registries": {
    "ui": "https://example.com/registry.json"
  }
}

Object format (authenticated registries):

JSON
{
  "registries": {
    "private": {
      "url": "https://private.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Both formats can be mixed in the same config. You can configure as many registries as you want. When adding a block without a namespace, the CLI searches all of them.

Authentication

Registries that require authentication use the object format with headers. The CLI sends these headers on every request to that registry, including both the registry.json fetch and individual file downloads.

Bearer token

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

Basic auth

JSON
{
  "registries": {
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Basic ${REGISTRY_CREDENTIALS}"
      }
    }
  }
}

Custom headers

Any header can be added. This works for API keys, org identifiers, or whatever your registry server expects:

JSON
{
  "registries": {
    "internal": {
      "url": "https://blocks.internal.company.com/registry.json",
      "headers": {
        "X-API-Key": "${BLOCKS_API_KEY}",
        "X-Org-ID": "acme"
      }
    }
  }
}

Environment variables

Header values support ${VAR_NAME} syntax for reading environment variables. This keeps tokens out of version control.

The CLI resolves environment variables at runtime. If a referenced variable is not set, the CLI exits with an error naming the missing variable and the header it was used in.

Set the variable in your shell or CI environment. The CLI reads the process environment only; it does not load .env files on its own:

Shell
export REGISTRY_TOKEN=ghp_abc123
npx blockstudio add private/hero

Static header values (without ${...}) are passed through as-is.

Config discovery

The CLI walks up from the current working directory looking for blocks.json. This means you can run commands from any subdirectory of your project.

Code
my-theme/
  blocks.json        <- found here
  blockstudio/
    hero/
  templates/
    page.php          <- running `npx blockstudio add` here still works

If no blocks.json is found, the CLI tells you to run npx blockstudio init.

Example: theme with two registries

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.mycompany.com/ui/registry.json",
    "internal": "https://blocks.mycompany.com/internal/registry.json"
  }
}

Example: plugin with custom directory

JSON
{
  "$schema": "https://blockstudio.dev/schema/blocks.json",
  "directory": "src/blocks",
  "registries": {
    "starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
  }
}