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
{
"$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):
{
"registries": {
"ui": "https://example.com/registry.json"
}
}
Object format (authenticated registries):
{
"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
{
"registries": {
"private": {
"url": "https://api.example.com/registry.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
Basic auth
{
"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:
{
"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:
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.
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
{
"$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
{
"$schema": "https://blockstudio.dev/schema/blocks.json",
"directory": "src/blocks",
"registries": {
"starter": "https://raw.githubusercontent.com/acme/blocks/main/registry.json"
}
}