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

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.

If your app is already initialized and running, use only init and continue with its existing dev server.

3. Publish your module

Open another terminal in the app directory:

cd my-app
npm login
gh auth login # only if you want a dedicated GitHub repository
npx create-mercato-module publish visits

The wizard asks for the npm package name, version, optional GitHub repository, and public or restricted access. It builds an archive, shows the destinations and any warnings, and publishes only after you retype the package name. Complete npm's 2FA verification when requested.

Settings are remembered in .mercato/module-tool.json; later releases reuse them and default to the next stable patch version. Use --configure to change them. Your app's module, other modules, and Git origin stay in place.

4. Install it in another app

Once npm makes the published version available, run inside the receiving app:

npx create-mercato-module install @your-name/mercato-visits

install delegates registration and generation to Open Mercato, and also accepts a dedicated GitHub repository when the package is not on npm:

npx create-mercato-module install your-name/mercato-visits
npx create-mercato-module install your-name/[email protected]
npx create-mercato-module install https://github.com/your-name/mercato-visits.git

Scoped npm packages, npm:unscoped-package, GitHub URLs, owner/repository, and a bare repository name for your authenticated GitHub account are supported. Use --eject for packages that allow source ejection, or --module <module_id> to choose one module from a multi-module package. GitHub installs use the current default-branch head unless owner/repo@version-or-ref, owner/repo#ref, or --ref <tag-or-commit> selects another ref. Like npm's [email protected], owner/[email protected] selects a version: it tries the exact 1.2.3 ref first, then v1.2.3 only if the exact ref is missing. Prereleases such as @1.2.3-beta.1 follow the same rule. #ref and --ref always select an exact Git ref. The resolved full commit is pinned in every case.

Publish an existing module

If src/modules/visits/index.ts already exists, publish it directly:

npx create-mercato-module publish visits \
  --package @your-name/mercato-visits \
  --repo your-name/mercato-visits

Keep developing locally and run the same command for later releases. The app can have its own Git repository or no Git repository at all.

Develop in a dedicated repository

Run inside any Open Mercato app. Give link a repository or an npm package:

npx create-mercato-module link pkarw/visits-example
# These work too:
npx create-mercato-module link https://github.com/pkarw/visits-example.git
npx create-mercato-module link @piotrkarwatka/visits

The npm form discovers the GitHub repository from the package's npm metadata. The package name and module ID come from the repository; no npm package name prompt or prior init is needed. A bare repository name uses your authenticated GitHub account unless an unsaved local module has the same name; in that legacy case, the command asks for its dedicated repository. Use owner/repository to remove the ambiguity. If the package has no dedicated module repository, the command explains how to fix it.

Optionally name the local checkout folder:

npx create-mercato-module link pkarw/visits-example my-visits

The tool clones under .mercato/module-repos/my-visits (default: the module ID), links src/modules/visits, registers it as @app, and runs generation. Existing local source is backed up. The local folder name does not change the module ID, routes, or imports.

Edit through the app, then release from the linked repository using the saved package and repository settings:

npx create-mercato-module publish visits

Publication includes your linked edits, preserves repository customizations, and suggests the next patch version. link visits still works when the repository is saved. For a new local module, publish it with publish visits --repo owner/repo before linking it.

This link is local: a fresh clone of the whole app needs the module source restored or linked again. See repository development and PR workflow for details.

In an Open Mercato Cloud sandbox

The sandbox already contains an installed app. From its terminal in /workspace:

npx create-mercato-module init visits
npx create-mercato-module publish visits

The app keeps its repository while the selected module gets its own package and optional repository.

Preview before you publish

npx create-mercato-module publish visits \
  --package @your-name/mercato-visits \
  --dry-run

This builds a real .tgz under .mercato/module-publish/, without login or publication. See the command reference for repository, version, access, and automation options.

Documentation

| Topic | Guide | |---|---| | Commands and flags | Command reference | | Login and npm tokens | Authentication | | GitHub Actions without a write token | Trusted Publishing | | Contents, dependencies, and portable imports | Package contents | | Errors mentioning .mercato/generated | Generated-import errors | | Settings, Git, and releases | Release behavior | | Run the unreleased GitHub version | GitHub installation | | Contribute and run checks | Development | | Verify clean app installs from npm and GitHub | Release tests |

Part of Open Mercato. Website · Framework docs · Cloud · Discord

MIT © Open Mercato contributors. See LICENSE.