A community monorepo for publishing ready-to-install @open-mercato/* modules that extend Open Mercato without touching its core.
Open Mercato ships with a module system that lets you add features to your app without forking or modifying the platform. This repo is where the community publishes those features.
Every module here:
- 🔌 Installs in one command — no manual wiring, no config files to edit
- 🔒 Stays isolated — each module is its own npm package that hooks into the platform through declared extension points, never by patching core code
- 🧬 Is ejectable — run
--ejectto copy the module into your app and own it fully - 🤝 Gets reviewed — every submission goes through core team review before reaching npm
Whether you're adding a small UI widget or shipping a full vertical feature with its own entities, API routes, and admin pages — if it runs on Open Mercato, it belongs here.
Modules are published under @open-mercato/* and installed into any standalone Open Mercato app via the mercato CLI:
# Install and activate in one step
yarn mercato module add @open-mercato/<module-name>
# Copy the source code locally for full ownership
yarn mercato module add @open-mercato/<module-name> --eject
# If the package is already installed, copy it locally without reinstalling
yarn mercato module enable @open-mercato/<module-name> --ejectRunning module add fetches the package from npm, auto-discovers the module it contains, registers it in your app's src/modules.ts, and runs the code generators. Apply migrations and you're live.
Each package integrates through UMES extension points: widget injection, event subscribers, response enrichers, API interceptors, and custom entities. Core packages stay untouched and upgradeable.
Clone the repo and spin up the sandbox environment to start building:
git clone https://github.com/open-mercato/official-modules.git
cd official-modules
cp apps/sandbox/.env.example apps/sandbox/.env
docker compose up --build -d
yarn install
yarn install-skills
yarn generate
yarn initialize
yarn devNavigate to http://localhost:3000/backend and sign in with the credentials printed by yarn initialize.
The sandbox is a full Open Mercato app wired to all workspace packages. Any package you build under packages/ is immediately available to it — no registry publish required.
| Package | Description | Author |
|---|---|---|
| — | No modules yet. Be the first to contribute! | — |
Modules are installed into your standalone Open Mercato app using the mercato CLI.
Install and register in one step:
yarn mercato module add @open-mercato/<module-name>Apply database migrations and start:
yarn generate
yarn mercato db:migrate
yarn devInstall a specific version or tag:
yarn mercato module add @open-mercato/<module-name>@previewTake local ownership of the package:
yarn mercato module add @open-mercato/<module-name> --ejectWhen added with --eject, the module is copied into your src/modules/<moduleId>/ directory. You own the code — edit it freely while the rest of the platform stays on npm.
If the package is already in node_modules and only needs activating:
yarn mercato module enable @open-mercato/<module-name>If the package is already installed and you want local ownership immediately:
yarn mercato module enable @open-mercato/<module-name> --ejectFull CLI reference: docs.openmercato.com/cli/module-add
Community modules live in packages/<module-name>/ and are published under the @open-mercato/ scope. The recommended workflow for humans and AI agents is:
spec-writing → scaffold-module → implement-spec
Before writing code, document your module in .ai/specs/SPEC-YYYY-MM-DD-<title>.md. This is the design document that implement-spec reads to know what to build. You might (and probably shall) use the spec-writing skill - available in any of the LLM coding envs. you're using after running the yarn install-skills
Minimum sections: TLDR · Problem Statement · UMES extension points used · Data models · API contracts · Phases.
Use the scaffold-module skill (in .ai/skills/scaffold-module/SKILL.md) to generate the complete package skeleton from your spec. It produces all required files — package.json, build config, acl.ts, setup.ts, a placeholder backend page — ready to build immediately.
# After scaffold, verify it builds cleanly
yarn workspace @open-mercato/<your-module> build
yarn workspace @open-mercato/<your-module> typecheckUse the implement-spec skill to fill in the business logic phase by phase: entities, validators, API routes, UI pages, events, widget injection. Every phase must pass the code-review compliance gate before moving to the next.
The sandbox is a workspace sibling — no registry publish needed. Add your module to apps/sandbox/src/modules.ts:
{ id: '<module_id>', from: '@open-mercato/<module-name>' },Then build and start:
yarn build:packages # build the package first
yarn generate # regenerate sandbox registry
yarn mercato db:migrate # apply any new migrations
yarn dev # open localhost:3000/backendNavigate to /backend/<module-name> and confirm the module loads, pages render, and APIs respond. Remove the entry from modules.ts before opening a PR.
Open a PR against develop. See CONTRIBUTING.md for the full checklist. The core team will review and, once approved, publish to npm.
Note: The app/sandbox changes should be limited to enabling your module, and potentially nothing more - as the users will be using your module without this app (with their own, created with the create-mercato-app command).
- Package name:
@open-mercato/<module-name>(kebab-case) - Module ID inside the package:
snake_case(e.g.my_module) — derived by replacing-with_ - Peer dependencies: declare
@open-mercato/sharedand@open-mercato/uias peer deps; pin to the same version - Exports: follow the export map in
packages/test-package/package.jsonexactly ejectable: trueinindex.tsmetadata if you want consumers to be able to take source ownership- Every module MUST use UMES extension points — it MUST NOT modify core packages
We welcome modules of all sizes — from thin UI extensions to full vertical feature sets.
- Fork open-mercato/official-modules and create a branch:
feat/<module-name>. - Follow the Getting Started guide to set up your local environment.
- Write a spec in
.ai/specs/, scaffold the package, implement the spec — see AGENTS.md for the full agentic workflow. - Open a PR against
developwith a description of what the module does, screenshots or a short demo, and the testing you performed.
The core team reviews all submissions. Read CONTRIBUTING.md for the full branching conventions and PR checklist. Open Mercato is proudly supported by Catch The Tornado.
MIT — see LICENSE for details.