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:

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:

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:

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": [...]
}

Welcome

Legal

How it works

registry.json

Block properties

File types

Building

Hosting

Using custom registries

Authentication

Dependencies between blocks

​How it works

​registry.json

​Block properties

​File types

​Building

​Hosting

​Using custom registries

​Authentication

​Dependencies between blocks

How it works

registry.json

Block properties

File types

Building

Hosting

Using custom registries

Authentication

Dependencies between blocks