melonJS Plugin Template

A starter template for melonJS plugins, in TypeScript, built with esbuild and tested in a headless browser with Vitest.

1. Use this template (or clone it)

2. Install the dependencies, and the browser the tests run in:

   npm install
   npx playwright install chromium
   

3. In package.json, set your plugin's name, description, homepage and repository, and the lowest melonJS version it needs in peerDependencies

4. Rename MyPlugin and write your plugin in src/index.ts

import { plugin } from "melonjs";
import { MyPlugin } from "my-plugin";

// once the application is created
plugin.register(MyPlugin, "myPlugin");

// then, anywhere
plugin.cache.myPlugin.hello();

plugin.register passes any extra arguments to the plugin's constructor. The template takes the application it belongs to, so on a page with several applications:

plugin.register(MyPlugin, "myPlugin", app);

npm publish cleans, builds and tests first.

src/
└── index.ts        # the plugin
tests/
└── plugin.spec.ts  # its tests, run in a real browser
scripts/
├── build.ts        # esbuild configuration
└── clean.ts
dist/               # generated output (gitignored)

These are the ones the official plugins follow:

• One version to maintain. The lowest melonJS version the plugin runs on is read from peerDependencies.melonjs, and plugin.register refuses to run it on an older engine. The peer range alone only warns at install time, and never when melonJS comes from a CDN.
• Use this.app, not the global game: it is the application the plugin was registered for.
• melonJS stays external. The build leaves melonjs out of the bundle, so the game and the plugin share one engine.
• Real browser tests. melonJS needs a canvas and a DOM, so the tests create a real Application (await app.init()) in headless Chromium.

The official plugins in the melonJS repository (debug-plugin, spine-plugin, capacitor-plugin, tiled-inflate-plugin) are good examples to read.

• Discord: chat with the community
• Forum: ask questions
• API Docs: full API reference
• Wiki: tutorials and guides