Package manifest

Required package structure

The installer resolves <packageName>/package.json and reads the sellforge block. That block must contain a displayName. The package must also provide a usable name, version, and import entry point.

If you add a package exports map, keep ./package.json resolvable as well as the plugin's main entry point.

{
  "name": "@sellforge-plugin/hello",
  "version": "0.1.0",
  "type": "module",
  "main": "./index.js",
  "files": ["index.js", "migrations"],
  "sellforge": {
    "displayName": "Hello Sellforge",
    "description": "A minimal order-event extension.",
    "settings": {
      "namespace": "hello.",
      "keys": [
        {
          "key": "hello.label",
          "description": "Label attached to log messages",
          "default": "Hello",
          "required": false,
          "secret": false
        }
      ]
    }
  }
}

Settings metadata

The settings endpoint reads sellforge.settings.namespace and sellforge.settings.keys.

The context's settings.get() reads stored values. Apply a default explicitly in your code when a key has not been saved:

const label = (await ctx.settings.get('hello.label')) ?? 'Hello'

What metadata does not do

The manifest is stored with the installed record. Additional fields such as hooks, category, or coreVersion may describe a package, but the current loader registers behavior through executable code. Declare event handlers with ctx.hooks.on().

The installer does not enforce a coreVersion compatibility range, and the runtime does not automatically install an admin page or HTTP route based on manifest metadata.

Migration location

SQL migrations are discovered in the package's root migrations/ directory. Include that directory in the published package. See Migrations.