ERP Plugin Developer Docs

Appearance

Quickstart: a one-page plugin, live ​

By the end of this page you will have a plugin installed on your ERP tenant with one working page reachable from the app menu. Every command is real against the current erp CLI.

0. Prerequisites ​

  • Node.js 20+.
  • The plugin SDK on your PATH (the erp command). Until the SDK is published to npm you run it directly: node <sdk>/tools/erp-cli/erp.mjs. Substitute that for erp below.
  • The base URL of your ERP (e.g. https://erp.example.com).

1. Point the CLI at your ERP and log in ​

bash
erp env use prod --base-url https://erp.example.com
erp login

erp login opens your browser, you authorize the CLI, and the session is written to ~/.erp/config.json. Confirm it:

bash
erp whoami

2. Sync the authoring bundle (optional but recommended) ​

bash
erp env sync

This pulls your ERP's schema/catalog/example/doc bundle into ~/.erp/cache/. If your ERP does not expose the bundle endpoint yet, this no-ops and the SDK falls back to the bundle shipped inside the SDK package — you can keep going.

3. Wire up the MCP server for your IDE agent ​

bash
erp mcp install

Writes a .mcp.json in the current directory pointing at the erp-plugin-language MCP server, so Claude Code / Cursor / Codex can call erp_get_schema, erp_list_blocks, erp_platform_catalog, erp_search_docs, erp_examples_patterns, erp_validate_page, and the rest.

4. Scaffold the plugin ​

bash
erp plugin create acme-hello --name "Acme Hello" --type business-app

This creates acme-hello/ with a spk-assembly/ tree (plugin.json, metadata/page/, metadata/menu/, metadata/i18n/, …).

No Java needed. The scaffold leaves plugin.json's mainClass null and that is exactly right for a pure-JSON plugin — the platform loads it through a built-in generic entry point. You compile a Plugin class only if your plugin ships its own Java behaviour. See Create a plugin from scratch.

Author one page under spk-assembly/metadata/page/hello.json. Ground yourself first — do not guess the shape:

bash
erp schema pull page                 # the page.json contract
erp blocks list --category display   # what widgets exist
erp examples patterns --kind page    # curated real page shapes

Give the page a menu entry:

bash
erp menu create acme-hello acme-hello.main --display-name "Hello" --route /hello

5. Validate before you ship ​

bash
erp plugin validate acme-hello/spk-assembly
erp plugin test acme-hello/spk-assembly      # semantic lints (i18n keys, grid data-source, …)

Fix anything flagged. These are the same checks the platform runs at install time — a clean run here means a clean install.

6. Build and publish ​

bash
erp plugin build acme-hello/spk-assembly -o acme-hello.spk
erp plugin publish acme-hello.spk

7. See it live ​

Open your ERP, navigate to the app that owns the module, and you'll find the Hello menu item. The page URL is /app/<app>/<module>/acme-hello/hello (the route pattern in your menu file is not the browser URL — see troubleshooting/known-gotchas.md).

Next ​