Module anatomy

A module is a plain Node.js project with two files the platform requires: module.json (identity in the registry) and index.js (entry point in the container). The example module has the minimal layout:

acme-hello/
├── module.json        # required: code, version, module dependencies
├── package.json       # npm dependencies, "main": "index.js"
├── .npmrc             # optional: @orbito scope line, if not in ~/.npmrc
├── index.js           # required: entry point, registers everything
└── pages/
    └── hello.yaml     # OVE view registered with Pages.registerPages

omm init writes these files plus a .gitignore.

Larger modules add src/ (business logic), methods/ (one file per method, loaded with Utils.loadMethods), test/ and README.md. A README.md inside the package becomes the version description in the registry.

module.json

The manifest is the only source of the module's identity. omm validates it before upload and the registry validates it again on upload and on release.

{
    "name": "acme/hello",
    "version": "0.1.0",
    "dependsOn": ["core/orders"],
    "singleton": true,
    "secrets": [
        { "name": "ACME_API_KEY", "description": "Application key of the Acme API" }
    ]
}

Details in Polish: Module structure.

index.js

The container runs node index.js in the module directory (image node:20-alpine). The file registers everything at top level:

• Core.registerMethod for every method the front end, automations or other modules call,
• Core.registerHook for every hook the module answers,
• Pages.registerPages for OVE views, Config.registerConfigBlocks for settings,
• Core.onEnabled / Core.onDisabled for lifecycle events.

Requiring @orbito/api-lib opens the connection to the core. Calls made before the connection is ready are queued, and registrations are re-sent automatically after a reconnect, so top-level registration is all you need. Point to files relative to the module, for example path.join(__dirname, 'pages', 'hello.yaml').

Modules and the SDK are CommonJS: use require / module.exports, 'use strict'; at the top, and no "type": "module" in package.json.

The full example is acme/hello.

package.json

{
    "name": "acme-hello",
    "version": "0.1.0",
    "private": true,
    "main": "index.js",
    "dependencies": {
        "@orbito/api-lib": "^4.3.0",
        "fastest-validator": "^1.19.1"
    }
}

• main must be index.js.
• The registry build runs npm install --only=production, so everything the module requires at runtime belongs in dependencies. Commit package-lock.json for reproducible builds.
• node_modules/ is never packed; the build installs dependencies itself.
• @orbito/api-lib is not on npmjs.org: it lives in the Orbito npm registry. npm install needs the scope line @orbito:registry=https://git.kozminski.net.pl/api/packages/orbito/npm/, either in ~/.npmrc (npm config set @orbito:registry https://git.kozminski.net.pl/api/packages/orbito/npm/, once per machine) or in a .npmrc in the module directory. The line holds no token, so it is safe in the module directory, but omm does not pack .npmrc by default and the registry build uses its own .npmrc anyway.
• Keep version equal to module.json. Only module.json is checked, but a drift confuses humans.

Versioning

• module.json version is the version of the package. You change it by hand; omm never does.
• A new version must be higher than the last released version of the module.
• Publishing the same version again overwrites a draft (useful when a build failed). A released version is immutable.
• Drafts do not need a new version. omm publish overwrites the draft of the same version, and omm update on the version the instance already runs reloads it with the fresh draft image. Bump the version before omm publish --release (and before the first draft after a release), or when you want to keep the previous draft untouched.

What omm publish checks

Locally, before anything is sent:

1. module.json exists and is valid JSON.
2. name, version, dependsOn, files and secrets follow the rules above.
3. The package is built without node_modules/, .git/, .env*, .npmrc, *.zip, .gitignore, .dockerignore, CLAUDE.md and editor directories. Preview it with omm pack --dry-run.

In the registry:

1. A module card with exactly this name exists and the logged-in account is a member of its namespace. omm init creates it; omm publish never does.
2. The manifest is valid for that card.
3. The version is higher than the last released one and is not an already released version.
4. The Docker image builds. omm publish waits for the build (default 600 s, --timeout) and prints the build error when it fails.
5. With --release only: the draft becomes published, the previously published version becomes deprecated, and every declared secret without a value is printed as a warning.

Details in Polish: Packaging, omm.