The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
---
title: "Registry"
description: "Create, build, and host your own block registry."
---
A registry is a collection of blocks that can be installed into any Mercur project using the CLI. The official Mercur registry (`@mercurjs`) provides all the built-in marketplace blocks. You can also create and host your own.
## How it works
A registry is a set of JSON files — one per block — served over HTTP. When you run `bunx @mercurjs/cli@latest add`, the CLI fetches the block's JSON, resolves its dependencies, and copies the source files into your project.
```
registry/
├── registry.json # Registry definition with all blocks
├── src/
│ └── my-block/ # Block source files
│ ├── modules/
│ ├── workflows/
│ └── api/
└── r/ # Built output (generated)
├── registry.json
└── my-block.json # Block JSON with embedded file contents
```
## registry.json
The `registry.json` file defines your registry and all its blocks:
```json registry.json
{
"$schema": "https://registry.mercurjs.com/registry.json",
"name": "@my-org",
"homepage": "https://my-org.com",
"items": [
{
"name": "reviews",
"description": "Product and seller reviews with ratings.",
"dependencies": [],
"registryDependencies": [],
"docs": "## Configuration\n\nAdd the review module to your `medusa-config.ts`...",
"files": [
{
"path": "reviews/modules/reviews/index.ts",
"type": "registry:module"
},
{
"path": "reviews/workflows/review/workflows/create-review.ts",
"type": "registry:workflow"
},
{
"path": "reviews/api/store/reviews/route.ts",
"type": "registry:api"
}
],
"categories": ["module", "workflow", "api"]
}
]
}
```
### Block properties
| Property | Description |
| ---------------------- | -------------------------------------------------------------- |
| `name` | Block identifier used in `bunx @mercurjs/cli@latest add` |
| `description` | Short description shown in search results |
| `dependencies` | NPM packages to install |
| `registryDependencies` | Other blocks this block depends on (e.g. `@mercurjs/wishlist`) |
| `docs` | Markdown shown to the user after installation |
| `files` | List of source files with their paths and types |
| `categories` | Tags for search and filtering |
### File types
Each file in a block has a `type` that determines where it gets placed in the target project:
| Type | Target alias |
| ------------------- | ------------ |
| `registry:module` | `modules` |
| `registry:workflow` | `workflows` |
| `registry:api` | `api` |
| `registry:link` | `links` |
| `registry:vendor` | `vendor` |
| `registry:admin` | `admin` |
| `registry:lib` | `lib` |
These map to the aliases defined in the consumer's `blocks.json`.
## Building
Build your registry into distributable JSON files:
```bash
bunx @mercurjs/cli@latest build
```
This reads `registry.json`, resolves all imports for each block, embeds the file contents, and outputs one JSON file per block to the `r/` directory.
| Option | Description |
| --------------------- | --------------------------------- |
| `-o, --output <path>` | Output directory (default: `./r`) |
| `-v, --verbose` | Show detailed output |
The build step also automatically resolves NPM dependencies from your source imports — you don't need to list every transitive dependency manually.
## Hosting
Serve the built `r/` directory over HTTP. Any static hosting works — GitHub Pages, Vercel, Netlify, S3, or your own server. The only requirement is that `{name}.json` files are accessible at a public URL.
## Using custom registries
Add your registry to `blocks.json` in any Mercur project:
```json blocks.json
{
"registries": {
"@my-org": "https://my-registry.com/r/{name}.json"
}
}
```
Use `{name}` as a placeholder for block names. Then install blocks from it:
```bash
bunx @mercurjs/cli@latest add @my-org/reviews
```
### Authentication
For private registries, you can use headers with environment variables:
```json blocks.json
{
"registries": {
"@my-org": {
"url": "https://api.my-org.com/r/{name}.json",
"headers": {
"Authorization": "Bearer ${REGISTRY_TOKEN}"
}
}
}
}
```
## Dependencies between blocks
Blocks can depend on other blocks using `registryDependencies`. When a user installs your block, the CLI automatically resolves and installs all dependencies in the correct order.
```json
{
"name": "order-tracking",
"registryDependencies": ["@mercurjs/wishlist"],
"files": [...]
}
```