---
title: "Blocks"
description: "Self-contained pieces of marketplace functionality that get copied into your project as source code."
---

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

```bash
bunx @mercurjs/cli@latest add reviews
bunx @mercurjs/cli@latest add wishlist product-import-export
```

The CLI fetches the block from the [registry](/developer-guide/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:

| Type | What it is | Example |
|------|-----------|---------|
| **Modules** | Data models and business logic | Review model, wishlist service |
| **Workflows** | Multi-step business processes | Create review, export products |
| **API Routes** | HTTP endpoints | `GET /store/reviews`, `POST /vendor/products/import` |
| **Links** | Relationships between modules | Product-review link, customer-wishlist link |
| **Vendor extensions** | Vendor portal pages and components | Reviews list page, import drawer |
| **Admin extensions** | Admin panel pages and components | Reviews 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`:

```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:

```bash
bunx @mercurjs/cli@latest diff reviews
```

If there are updates you want, re-install with the overwrite flag:

```bash
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:

```bash
bunx @mercurjs/cli@latest search
bunx @mercurjs/cli@latest search --query wishlist
```

View details about a specific block:

```bash
bunx @mercurjs/cli@latest view reviews
```