Skip to main content
Blocks are the unit of distribution in Mercur. Each block is a self-contained feature — a reviews system, a wishlist, product import/export — that you install directly into your project. Unlike packages, blocks are copied as source code. You own every file and can modify anything.

​
Installing blocks

The CLI fetches the block from the registry, resolves dependencies, transforms imports to match your project’s path aliases, and copies the files into the right directories.

​
What’s inside a block

A block can contain any combination of: For example, the reviews block includes a module (data model + service), workflows (create/update/delete), API routes (store, vendor, admin), links (product-review, seller-review), and UI pages for both the vendor portal and admin panel.

​
Block structure

Blocks follow a consistent directory convention:
Files are placed into your project based on the aliases in your blocks.json:
blocks.json

​
Post-installation

After adding a block, the CLI shows setup instructions. Typically you need to:
  1. Register the module in medusa-config.ts
  2. Add middlewares to your api/middlewares.ts
  3. Run migrations with bunx medusa db:generate and bunx medusa db:migrate
  4. Regenerate types with bunx @mercurjs/cli@latest codegen

​
Updating blocks

Check for changes against the registry:
If there are updates you want, re-install with the overwrite flag:
Since blocks are source code in your project, you control when and how updates are applied.

​
Available blocks

Search the registry to see what’s available:
View details about a specific block: