Yeoman generator

generator-mantis scaffolds a working Mantis extension in one command: a valid mantis.extension.json, a host entry, one panel, an optional Python backend, and a script that builds the installable package. It is the fastest way to get from an empty folder to something you can import.

KellisLab/generator-mantisYeoman generator for Mantis extension bundles.npm: generator-mantis

Install

The generator runs on top of Yeoman, so install both:

npm install -g yo generator-mantis

Confirm Yeoman found it. mantis should appear in the list:

yo --generators

Scaffold a new extension

Run this in an empty directory. The generator writes into the current folder, not into a subfolder named after your extension.

yo mantis

It asks ten questions:

Prompt	Default	Notes
Extension id (reverse-DNS style)	com.example.hello	Letters, numbers, ., _, -. Validated before anything is written.
Display name	Hello Mantis
Version	0.1.0
Description	a one-line default
Publisher (optional)	empty	Omitted from the manifest when blank.
Homepage URL (optional)	https://home.withmantis.com
First panel id	main	Becomes the panel entry path and the onPanel: activation event.
First panel title	Hello	Shown in the Verticals menu.
Include sample Python backend (echo action)?	no	Choosing yes also forces backend:invoke into the permission list.
Permissions	maps:read, selection:read, panels:write pre-checked	A checkbox list.

There is no “include a panel” question. A panel is always scaffolded.

Leave selection:write unchecked

The permission checklist offers selection:write, but the Mantis install validator rejects it. If you check it, yo mantis succeeds and node pack-bundle.cjs succeeds, and then the import fails with “Unknown or unsupported extension permissions”. That is a gap in the generator’s choice list, not a mistake in your project.

What you get

my-extension/
  mantis.extension.json
  extension.js
  panel/
    <panelId>.js
  pack-bundle.cjs
  backend/
    main.py        # only if you asked for the Python backend

The manifest sets main to extension.js at the project root and the panel entry to panel/<panelId>.js. Activation events are onStartup and onPanel:<panelId>. There is no dist/ directory, no stylesheet, no package.json, and no README.md. If you want a build step, add one yourself and point the manifest paths at its output.

Package it

The generator emits its own packaging script, which needs nothing beyond Node:

node pack-bundle.cjs

It reads mantis.extension.json, collects main, every panel’s entry, scripts and styles, and the backend entry if present, then writes two files:

• package.mantisx, a zip you upload through the Mantis import dialog or with mantis use install_extension
• bundle.json, the same content as a single JSON document, which the import dialog also accepts

Everything is gathered from the manifest, so a file you forgot to reference is simply not packaged. Every file is read as UTF-8, matching the server rule that packages contain text only.

Add another panel

From the same folder, after yo mantis:

yo mantis:panel

It asks for a panel id and title, appends the panel to contributes.panels, adds the matching onPanel:<panelId> activation event, and writes panel/<panelId>.js. It refuses to run if there is no mantis.extension.json in the directory, and refuses a panel id that already exists.

Re-run node pack-bundle.cjs afterward to pick up the new file.

When to use it

Use the generator when starting a new extension from scratch. It keeps manifestVersion, apiVersion, the panel entry path, and the activation events consistent with each other, which is where hand-written manifests usually go wrong.

Use the manual setup in Quick start when you want to understand every file, or when the extension lives inside an existing repository that already has its own build tooling.

Read nextPackaging and installationWhat the import validator checks, and how installs are scoped.