GitHub
GitHub is the simplest way to host a registry. Push your blocks to a repository and use GitHub’s raw content URLs.
Setup
Create a repository with this structure:
acme-blocks/
registry.json
blocks/
hero/
block.json
index.php
card/
block.json
index.php
style.scss
registry.json
Set baseUrl to the raw GitHub URL for your blocks/ directory:
{
"name": "acme",
"description": "Acme Corp block library.",
"baseUrl": "https://raw.githubusercontent.com/acme/acme-blocks/main/blocks",
"blocks": [
{
"name": "hero",
"title": "Hero",
"category": "layout",
"type": "blockstudio",
"files": ["block.json", "index.php"]
},
{
"name": "card",
"title": "Card",
"category": "components",
"type": "blockstudio",
"files": ["block.json", "index.php", "style.scss"]
}
]
}
The baseUrl uses raw.githubusercontent.com so the CLI gets the raw file
content, not the GitHub HTML page.
Consumer config
Users add your registry to their blocks.json:
{
"directory": "blockstudio",
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/main/registry.json"
}
}
Then:
npx blockstudio add acme/hero
Pinning to a release
To pin to a specific version, use a tag or commit SHA instead of main:
{
"registries": {
"acme": "https://raw.githubusercontent.com/acme/acme-blocks/v1.0.0/registry.json"
}
}
This prevents breaking changes from affecting existing projects, as long as
the registry.json at that tag also uses the tag in its baseUrl. The CLI
downloads block files from baseUrl, so a tagged registry.json whose
baseUrl still points at main installs the files from main. The same
applies to a commit SHA: it pins the block list, while the files come from
whatever ref that commit’s baseUrl names.
GitHub Pages
You can also serve a registry via GitHub Pages if you prefer a cleaner URL:
- Enable GitHub Pages for the repository
- Set
baseUrlto your Pages URL:https://acme.github.io/acme-blocks/blocks - The
registry.jsonis accessible athttps://acme.github.io/acme-blocks/registry.json
Private repositories
For private repos, use the object registry format with a GitHub personal access token:
{
"registries": {
"private": {
"url": "https://raw.githubusercontent.com/acme/private-blocks/main/registry.json",
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}"
}
}
}
}
Set the token in your environment:
export GITHUB_TOKEN=ghp_abc123
npx blockstudio add private/hero
The token needs repo scope (or contents:read for fine-grained tokens)
to access private repository content via raw.githubusercontent.com.