mercur-blocks
Discover, evaluate, install, and verify Mercur blocks in the basic starter using `blocks.json` aliases and CLI workflows.
- License 许可
- MIT
- 所属仓库
- amoai-tech/mdeai
- 最近更新
- 2026-11-13
- Stars
- ★ 2
- Forks
- 1
01 前言 Front Matter
- name
- mercur-blocks
- description
- Discover, evaluate, install, and verify Mercur blocks in the basic starter using `blocks.json` aliases and CLI workflows.
03 SKILL.md 正文
Mercur Blocks Workflow
Use this skill when:
- evaluating whether a block fits the starter project
- adding a block
- checking installed block impact
- updating a block and reviewing drift
Alias map
In the basic starter:
api->packages/api/srcadmin->apps/admin/srcvendor->apps/vendor/src
Think about block impact by alias destination, not just by name.
Workflow
- Search if the exact block name is not known.
- View the block before installation.
- Identify which aliases and workspaces it will touch.
- Add the block.
- When CLI asks to overwrite
middlewares.ts— always decline and merge manually. - Inspect the installed files and the block docs output.
- Apply all configuration from the block docs (middleware, medusa-config, env vars, migrations).
- Run
bun run devfrompackages/apiand check for startup errors before moving on.
Post-install checklist
- Did files land under
packages/api/src,apps/admin/src, orapps/vendor/src? - Does
packages/api/medusa-config.tsneed module or provider registration? - Did the block docs specify middleware to add to
src/api/middlewares.ts?- Check the actual export names and paths in the installed middleware files — block docs may have wrong paths.
- Verify the import path matches
./actual/folder/middlewaresnot a generic path from docs.
- Did the block add custom modules that need
db:generate <module>anddb:migrate?- Even if docs don't mention migrations, check if the module has a
models/directory — if it does, migrations are needed.
- Even if docs don't mention migrations, check if the module has a
- Did the block add UI routes? They must be under
src/routes/(notsrc/pages/) for the dashboard SDK to detect them. - Did the block add UI pages that need
export const config: RouteConfigfor sidebar visibility? - Did the block docs require env vars, plugin options, or config changes?
- Did the block specify npm dependencies? Install any that CLI didn't handle automatically.
Known issues with block docs
Block docs may contain inaccurate information. Always verify:
- Middleware import paths: docs may reference generic paths like
./admin/middlewareswhen the actual file is at./admin/<feature>/middlewares. - Middleware export names: check the actual
export constname in the installed file. - Missing dependencies: some blocks import npm packages not listed in their
dependenciesarray. - Missing migration instructions: some blocks with custom modules don't mention
db:generate/db:migratein docs. - File conflicts: multiple blocks may try to write the same file (e.g. workflow hooks). Decline overwrites and merge manually.
Middleware merging
When adding a block's middleware to src/api/middlewares.ts:
- Read the actual installed middleware file to get the correct export name and path.
- Add the import to the existing
middlewares.ts. - Spread it into the existing
routesarray.
Do NOT accept CLI's middleware overwrite — it replaces the entire file.
Useful commands
npx @mercurjs/cli@latest search --query <keyword>
npx @mercurjs/cli@latest view <block>
npx @mercurjs/cli@latest add <block>
npx @mercurjs/cli@latest diff <block>
Run CLI commands from the project root where blocks.json lives.
Run medusa commands (db:generate, db:migrate) from packages/api.
Avoid
- adding blocks without reviewing their docs first
- accepting middleware.ts overwrite from CLI
- ignoring config or env follow-up after install
- skipping
diffwhen reviewing block updates - trusting docs blindly — verify import paths and dependencies against installed files
04 同仓库更多 Skills
mde-pr-review-supabase
Use when reviewing MDE Supabase SQL, Auth and RLS changes in a pull request.
mde-pr-review-stripe
Use when reviewing MDE Stripe payments and webhooks changes in a pull request.
mde-pr-review-nextjs
Use when reviewing MDE Next.js App Router changes in a pull request.
mde-pr-review-mastra
Use when reviewing MDE Mastra agent, tool and workflow changes in a pull request.
mde-pr-review-maps
Use when reviewing MDE Google Maps and Places changes in a pull request.
mde-pr-review-copilotkit
Use when reviewing MDE CopilotKit and AG-UI changes in a pull request.