Custom Server
If GitHub doesn’t fit your needs, you can host a registry from any HTTP
server. The only requirement is that the registry.json and block files are
accessible via their URLs.
Static file server
The simplest option. Drop your registry.json and blocks/ folder on any
static hosting:
- Nginx/Apache: serve the directory directly
- Vercel/Netlify: deploy the directory as a static site
- S3/R2/GCS: upload the files to a bucket with public access
- CDN: put the files behind Cloudflare, Fastly, or any CDN
The CLI only needs GET access to the files. There’s no API, no dynamic
routes, no server-side logic required.
Dynamic server
If you want to generate registry.json dynamically (e.g. from a database,
or to add access control), you can build a simple API:
GET /registry.json -> returns the registry manifest
GET /blocks/{name}/{file} -> returns the block file content
{file} can contain slashes when a block lists files in subdirectories
(src/script.js), so the file route has to match nested paths.
The CLI doesn’t care how these endpoints are implemented. It makes plain
GET requests and expects the response body to be the file content.
Example: Express
const express = require('express');
const path = require('path');
const app = express();
app.get('/registry.json', (req, res) => {
res.sendFile(path.join(__dirname, 'registry.json'));
});
app.use('/blocks', express.static(path.join(__dirname, 'blocks')));
app.listen(3000);
Example: PHP
<?php
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
if ($path === '/registry.json') {
header('Content-Type: application/json');
readfile(__DIR__ . '/registry.json');
exit;
}
if (preg_match('#^/blocks/([^/]+)/(.+)$#', $path, $matches)) {
$file = __DIR__ . '/blocks/' . $matches[1] . '/' . $matches[2];
if (file_exists($file)) {
readfile($file);
exit;
}
}
http_response_code(404);
CORS
If the CLI runs in an environment where CORS matters (unlikely for a Node.js
CLI, but possible for future web-based tools), make sure your server sends
the appropriate Access-Control-Allow-Origin headers.
Caching
The CLI caches fetched registry.json files in memory during a single
command run. It does not persist caches across runs. If you want to optimize
for large registries, add standard HTTP caching headers
(Cache-Control, ETag) to your server responses.
Internal/corporate registries
For teams that want to share blocks internally:
- Host the registry on an internal server or VPN-accessible URL
- Each developer adds the registry URL to their project’s
blocks.json - The CLI fetches from that URL like any other registry
No special setup is needed. As long as the URL is reachable from the developer’s machine, it works.