Skip to main content
Blocks are complete features — backend module, workflows, API routes, and panel UI — installed as source code into your project. This tutorial installs the reviews block and follows it across every surface it touches.
Blocks are copied, not installed as dependencies. add writes the block’s source files into your project via the aliases in blocks.json — you own and can edit every file afterwards. Updates are opt-in through diff and add --overwrite. When you outgrow the catalog, build your own block.

​
Goal

Install reviews as a block and see it running everywhere it appears.

​
Install the block

1

Discover the block

Search the registry and inspect what the block ships before installing:
bunx @mercurjs/cli@rc search --query reviews
bunx @mercurjs/cli@rc view reviews
view lists the block’s files by target (API, admin, vendor) and its dependencies.
2

Install it

bunx @mercurjs/cli@rc add reviews
The CLI copies the source into the directories mapped by your blocks.json aliases and prints the block’s post-install instructions — module registration, middlewares, migrations.
3

Run migrations and codegen

The block introduced a reviews module, so generate and run its migrations, then refresh the typed route map:
cd packages/api
bunx medusa db:generate reviews
bunx medusa db:migrate
bunx @mercurjs/cli@rc codegen
4

See it live

Start the project — reviews now appear in the admin panel (moderation), the vendor portal (per-seller reviews), and the Store API (customer-facing review routes).

​
Verify

  1. The block’s files exist in your repo under the alias-mapped paths.
  2. Migrations ran cleanly and the API boots.
  3. The admin and vendor panels show their reviews pages; the store review endpoints respond.
  4. bunx @mercurjs/cli@rc diff reviews reports no drift from the registry.

​
FAQ

The CLI asks before overwriting existing files (or force it with --overwrite). If you’ve customized a page the block also ships, merge by hand — you’re merging source, not resolving package versions.
bunx @mercurjs/cli@rc diff reviews shows what changed in the registry since you installed. Take updates with add reviews --overwrite, re-applying any local edits afterwards.

​
Next steps

Add a custom panel page

Build your own block