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

bunx @mercurjs/cli@latest add reviews
bunx @mercurjs/cli@latest add wishlist product-import-export
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:
TypeWhat it isExample
ModulesData models and business logicReview model, wishlist service
WorkflowsMulti-step business processesCreate review, export products
API RoutesHTTP endpointsGET /store/reviews, POST /vendor/products/import
LinksRelationships between modulesProduct-review link, customer-wishlist link
Vendor extensionsVendor portal pages and componentsReviews list page, import drawer
Admin extensionsAdmin panel pages and componentsReviews moderation page
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: 
reviews/
├── modules/reviews/       # Data model, service, types
├── workflows/review/      # Steps and workflow definitions
├── links/                 # product-review, seller-review, etc.
├── api/
│   ├── admin/reviews/     # Admin API routes
│   ├── vendor/reviews/    # Vendor API routes
│   └── store/reviews/     # Store API routes
├── vendor/pages/reviews/  # Vendor portal UI
└── admin/pages/reviews/   # Admin panel UI
Files are placed into your project based on the aliases in your blocks.json:
blocks.json
{
  "aliases": {
    "api": "packages/api/src",
    "vendor": "apps/vendor/src",
    "admin": "apps/admin/src"
  }
}

​
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: 
bunx @mercurjs/cli@latest diff reviews
If there are updates you want, re-install with the overwrite flag: 
bunx @mercurjs/cli@latest add reviews --overwrite
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: 
bunx @mercurjs/cli@latest search
bunx @mercurjs/cli@latest search --query wishlist
View details about a specific block: 
bunx @mercurjs/cli@latest view reviews