create-mercato-module

Turn a custom Open Mercato module into an npm package and a dedicated GitHub repository. One CLI for creating, publishing, installing, and linking modules.

npx create-mercato-module init visits
# Build your feature in src/modules/visits.
npx create-mercato-module publish visits

Your application is the development workspace. This tool creates a portable package from one selected module, including its sources, compiled code, translations, and migrations. Publish it to npm, optionally give it a dedicated GitHub repository, and install it in another Open Mercato app.

Already built the module? Skip init and go straight to publish.

Quick start · Existing modules · Cloud sandboxes · Dry run · Commands · Docs · Discord

Quick start

You need Node.js 24+, Yarn 4, and Docker. On Windows, use WSL2. Already inside an installed app or Cloud sandbox? Skip step 1.

1. Create an Open Mercato app

npx create-mercato-app@develop my-app --preset empty
cd my-app
cp .env.example .env
docker compose up -d
yarn install

Follow the scaffold prompts to choose your AI coding tools. The develop channel provides the framework version used for this tool's standalone installation checks. See the Open Mercato installation guide for setup details.

2. Create and build your module

npx create-mercato-module init visits
yarn setup

init creates src/modules/visits, registers it as @app, and runs generation. yarn setup initializes your new app and starts its development server; leave it running. Open /backend/visits using the app credentials printed in the terminal, then build your feature in src/modules/visits.

The scaffold is a starting point: one page and its translations. From here you will probably want a coding agent to build the module out. The app already carries agent instructions (AGENTS.md) for the tools you chose in step 1, so open the app in your agent once yarn setup is running and describe the feature, for example: "In src/modules/visits, add a Visit entity with a list page and a create form." Keep the dev server running so you can check each change at /backend/visits.