Starting and shipping a project

Scaffolding

Start from the template rather than assembling a build by hand:

npm create melonjs@latest my-game

The project name is required — without it the command prints its usage and exits. It downloads the melonJS TypeScript boilerplate (Vite, TypeScript and the debug plugin already wired in), which saves you the top-level-await and asset-path issues that a hand-rolled config usually hits first.

Adding melonJS to an existing project

npm install melonjs

import { Application, Sprite, loader } from "melonjs";

The package is a tree-shakeable ES module with TypeScript declarations included and no runtime dependencies.

A CDN build exists for quick experiments, but not for production:

<script type="module">
    import { Application } from "https://cdn.jsdelivr.net/npm/melonjs@20/+esm";
</script>

Browser support and transpiling

The published bundle targets ES2022 and uses private class members. A browser that predates that cannot parse the file at all — it fails at load, not when a feature is used, so the symptom is a blank page with a syntax error.

To support older browsers, transpile melonJS together with your own code. The usual trap is that build setups skip node_modules by default, leaving melonJS untouched however low you set your target:

// vite.config.js — esbuild downlevels dependencies too
export default { build: { target: "es2020" } };

// webpack: the default `exclude: /node_modules/` would skip melonjs
{ test: /\.js$/, exclude: /node_modules\/(?!melonjs)/, use: "babel-loader" }

Two caveats worth knowing:

• Transpiling handles syntax only. Built-in methods need separate polyfills; a bundler's target setting will never add them.
• Downlevelled private class members become WeakMap lookups, and melonJS uses them in the renderer's hot paths. This is a real trade, not a free switch.

Native apps

Capacitor is the current recommendation for iOS and Android — see @melonjs/capacitor-plugin. Cordova also works and is documented, but is the older route.

The thing that breaks first in both is asset loading: the app is served from file://, where fetch() cannot read local files. melonJS's loader falls back to XHR for that scheme, so engine-loaded assets work — but any fetch() in your game code will fail there.

Mini-game platforms

WeChat Mini Games and Facebook Instant Games are both documented in the wiki. Note that device.platform.isWeixin detects WeChat's in-app browser, which is a normal WebView. WeChat Mini Games are a different runtime with no DOM, and need platform-specific adaptation rather than just detection — the one hook the engine offers is that the renderer adopts a globalThis.canvas when the runtime's adapter provides one, instead of creating its own.

Size

The whole engine is roughly 250 KB minzipped. Tree-shaking helps less than you might expect — the engine's subsystems reach each other, so a game importing a handful of symbols still pulls most of it. Budget for the full figure.

Practical wins are in assets, not the engine: pack sprites into atlases, prefer one tileset over several, and use stream: true for long music tracks so they are not decoded into memory.

Symptom → cause

symptom	cause
blank page, syntax error in the console	browser older than the ES2022 target
transpiling changes nothing	build config excludes node_modules
assets 404 in a packaged native app	fetch() in game code — file:// needs XHR
a built-in method is missing after transpiling	transpiling is syntax-only; polyfills are separate
bundle much larger than expected	tree-shaking recovers little — subsystems are interconnected

Related skills

• melonjs — the companion packages, including the Capacitor plugin
• melonjs-getting-started — the Application bootstrap the template produces