Skip to main content
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:
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

PropertyDescription
nameBlock identifier used in bunx @mercurjs/cli@latest add
descriptionShort description shown in search results
dependenciesNPM packages to install
registryDependenciesOther blocks this block depends on (e.g. @mercurjs/wishlist)
docsMarkdown shown to the user after installation
filesList of source files with their paths and types
categoriesTags for search and filtering

​
File types

Each file in a block has a type that determines where it gets placed in the target project:
TypeTarget alias
registry:modulemodules
registry:workflowworkflows
registry:apiapi
registry:linklinks
registry:vendorvendor
registry:adminadmin
registry:liblib
These map to the aliases defined in the consumer’s blocks.json.

​
Building

Build your registry into distributable JSON files: 
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.
OptionDescription
-o, --output <path>Output directory (default: ./r)
-v, --verboseShow 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:
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: 
bunx @mercurjs/cli@latest add @my-org/reviews

​
Authentication

For private registries, you can use headers with environment variables:
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. 
{
  "name": "order-tracking",
  "registryDependencies": ["@mercurjs/wishlist"],
  "files": [...]
}