Skip to main content

Step 1: Build your first Open Mercato app

The starter project ships with a working admin experience under src/. It renders a dashboard, login screens, and the auto-discovered modules that come from the packages you enable.

Open Mercato dashboard

Folder anatomy​

  • src/app/page.tsx – public landing page shown before authentication.
  • src/app/(auth) – authentication routes, including the login screen.
  • src/app/(backend)/backend/layout.tsx – wraps every admin page with navigation, RBAC checks, and locale providers.
  • src/app/(backend)/backend/[[...slug]]/page.tsx – catch-all backend router. It resolves requests to auto-discovered module pages, then falls back to files you place under src/modules/<module>/backend.
  • src/app/(frontend)/[[...slug]]/page.tsx – same mechanism for customer-facing pages. Frontend routes come from src/modules/<module>/frontend.
  • src/modules – local overrides. Drop a folder matching a module id (for example, auth or inventory) to replace pages, APIs, or entities from packaged modules.

The app boots with the core modules listed in src/modules.ts. Each entry points to a package and can be overridden by placing files under src/modules/<module>. When the CLI runs yarn modules:prepare, it scans enabled modules, merges overrides, and produces generated registries used by the runtime and admin UI.

Routing overlays​

  1. Packages publish default pages inside packages/<pkg>/src/modules/<module>/frontend|backend.
  2. At build time, any file in src/modules/<module>/<area>/<path> overrides the packaged version.
  3. The catch-all routers under src/app/(backend) and src/app/(frontend) read the generated registry and dispatch to the resolved React component.

Because everything flows through generated metadata, you can safely introduce new modules without touching the Next.js routers. For example, adding packages/inventory to modules.ts automatically exposes its backend pages at /backend/inventory/....

Module support files​

Every module—core or custom—uses a consistent set of files:

  • index.ts exports metadata (id, title, description, version).
  • acl.ts exports a features array used by RBAC.
  • di.ts registers services with the Awilix container.
  • data/entities.ts defines MikroORM entities. Optional extensions live beside them in data/extensions.ts.
  • data/validators.ts stores zod schemas for create/update operations.
  • backend/* and frontend/* contain Next.js server components with optional *.meta.ts files.
  • api/<method>/<path>.ts exposes API handlers. Each handler can include metadata for guards.

This tutorial will build on the stock app by adding an Inventory module. Before diving into module authoring, make sure you can run the shell commands below and see the admin dashboard running locally:

yarn install
yarn modules:prepare
yarn db:migrate
yarn dev

With the dev server running, log in using the seeded admin credentials. You are ready to customise the app.