Demo

Create a plugin

Use @quan-erp/cli to scaffold a plugin with quan-erp new, align names and versions, build with quan-erp watch, then register and install it on a local stack.

Overview

A plugin is one folder under plugins/ with module.metadata.json, a backend package, and a frontend package. Prefer quan-erp new / new-plugin to scaffold, or copy plugins/sample-es when you want a fuller reference layout.

  • Install @quan-erp/cli first (see Installation / CLI)
  • Run all quan-erp commands from the project root
  • Folder name = module.metadata.json name = npm scope suffix
  • Base stack must already be running (quan-erp base:dev)
@quan-erp/cli on npm →

1. Before you start

You need a Quark ERP project created with the CLI and a running base app.

  • Project scaffolded with quan-erp new-project (Installation)
  • @quan-erp/cli installed globally: npm i -g @quan-erp/cli
  • Base stack running: quan-erp base:dev
  • Node.js 18+ and a valid ~/.npmrc for @quan-erp/*
  • Pick a plugin name: lowercase kebab-case (e.g. fleet-management, hr, inventory)
TSQuick check
quan-erp help quan-erp base:dev # if base is not already up

2. Scaffold the plugin

Use the CLI when you want a clean empty plugin. Copy sample-es when you want working menus, pages, and API patterns to edit.

  • quan-erp new / new-plugin — interactive; good for greenfield plugins
  • sample-es — best reference for IPlugin, register(AppRegistry), api/, page/
  • Do not invent a custom top-level layout — keep backend/ + frontend/ + module.metadata.json
TSOption A — quan-erp new
1# From project root 2quan-erp new 3# or: quan-erp new-plugin 4# optional: quan-erp new-plugin --version latest 5# Prompts: name, description, module entry object, version 6# Creates plugins/<name>/{backend,frontend,module.metadata.json}
TSOption B — copy sample-es
cp -R plugins/sample-es plugins/my-plugin # Then rename packages + metadata.name (next section)

3. Align names (critical)

If these strings disagree, watch, install, and DI will fail in confusing ways. The CLI usually fills these in — still verify after scaffold.

  • name — unique plugin id used for API path prefixes, menus, and @Inject scope
  • pluginVersion — becomes the folder under available-plugins/<name>/<version>/
  • requiredBasedVersion — must match the base / @quan-erp/* version line
  • moduleEntryObject — root @Module class name exported from backend entry (usually Module)
  • pluginDependencies — other plugins that must load first (add later when you consume exports)
TSIdentity checklist
1plugins/<name>/ # folder 2module.metadata.json → "name": "<name>" 3backend/package.json → "@quan-erp-plugins/<name>-backend" 4frontend/package.json → "@quan-erp-plugins/<name>-frontend" 5@Module({ name: metadata.name, ... }) # backend root module
JSONmodule.metadata.json
1{ 2 "name": "my-plugin", 3 "type": "", 4 "pluginVersion": "1.0.0", 5 "description": "My first plugin", 6 "moduleEntryObject": "Module", 7 "requiredBasedVersion": "1.0.0", 8 "pluginDependencies": {} 9}

4. Align @quan-erp/* versions

Both backend and frontend package.json dependencies on @quan-erp/* must match the base images / BASE_VERSION. Mismatched versions break shared contracts.

  • Copy version pins from sample-es or from another working plugin on the same base
  • After changing versions, reinstall deps in plugins/<name>/backend and frontend
  • Rebuild with quan-erp watch after dependency changes
SHInstall deps
cd plugins/my-plugin/backend && npm install cd ../frontend && npm install cd ../../.. # back to project root

5. Add your first feature

Keep the first change small: one entity + service + controller on the backend, one page + api hook + menu/route on the frontend. Mirror sample-es folder names.

  • Backend — backend/src/index.ts (IPlugin), feature folder, schema/*.entity.ts, register providers on root @Module
  • Frontend — frontend/src/index.tsx register(AppRegistry): setAxiosClient, menu.add, route.add
  • API layer — frontend/src/api/<domain>/ with React Query; pages import hooks only
  • Namespace tables and HTTP paths with the plugin name (host prefixes routes automatically)
  • Do not import another plugin’s src/ — use Export services / frontend Export & expose APIs later

6. Build with quan-erp watch

From the project root, watch compiles backend + frontend and copies artifacts into base/available-plugins/<name>/<version>/.

  • Argument is the folder name under plugins/
  • Confirm base/available-plugins/my-plugin/<version>/ contains backend/, frontend/, module.metadata.json
  • Leave watch running while you iterate
TSTerminal
quan-erp watch my-plugin # one-shot production build quan-erp build:prod my-plugin

7. Local seed + UI install

On local/dev only, insert a module row so the plugin appears in the ERP UI, then Install to copy it into installed-plugins. Never SQL-seed UAT or production.

  • name / plugin_version / module_entry_object must match metadata
  • dependencies JSON should mirror pluginDependencies (use '{}' when empty)
  • After install, hard-refresh the browser if menus do not appear
  • If watch is running and the plugin is already installed, it also refreshes installed-plugins
SQLSQL (local/dev)
INSERT INTO module ("name","displayName","description","unInstallable","module_entry_object","plugin_version","dependencies","base_version","version") VALUES ('my-plugin','My Plugin','My first plugin',true,'Module','1.0.0','{}','1.0.0',1);
TSThen in ERP UI
# Open the running frontend # Find the plugin under available / modules # Install → copies to base/backend/installed-plugins/my-plugin/

Checklist

  • @quan-erp/cli installed; project created with quan-erp new-project
  • plugins/<name>/ exists with backend/, frontend/, module.metadata.json
  • metadata.name === folder name
  • package.json names are @quan-erp-plugins/<name>-backend|frontend
  • @quan-erp/* versions match the base stack
  • quan-erp watch <name> wrote available-plugins/<name>/<version>/
  • Local module row inserted (dev only)
  • Installed from ERP UI → installed-plugins/<name>/
  • register() adds at least one menu + route you can open

Next steps

  • Installation — project setup with quan-erp new-project
  • Folder structure — detailed trees for backend/frontend
  • CLI — watch / build:prod / pack:prod / new-project reference
  • Backend → Module lifecycle, Export services
  • Frontend → Plugins lifecycle, Export & expose APIs
  • Build with AI Agent — skills and pre-build prompts for faster scaffolding
InstallationFolder structureCLIBackend exportFrontend export