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