Skip to content

Cordova

Jump to bottom
Olivier Biot edited this page May 11, 2026 · 1 revision

Cordova

Apache Cordova wraps a web app as a native iOS / Android binary using each platform's system WebView. melonJS games built with Vite (or any bundler) drop into Cordova with no engine changes — WebGL, Canvas2D, audio, gamepads, and touch input all work the same way they do in a browser.

⚠️ Cordova is in low-maintenance mode. The project is still alive at Apache and produces releases, but most active investment in the JS-to-native-webview space has moved to Capacitor. For new mobile projects we recommend Capacitor (Ionic-maintained, modern plugin ecosystem, melonJS-specific glue via @melonjs/capacitor-plugin). This page is kept for existing Cordova-based projects that are not ready to migrate.

Install Cordova

npm install -D cordova

Use npx cordova … to invoke the CLI, or install it globally with npm install -g cordova if you prefer.

Scaffold a Cordova app around your game

The simplest setup uses Cordova's default project layout and copies your built game into the www/ folder it expects.

# 1. Create the Cordova project (sibling of your melonJS project, or inside it)
npx cordova create cordova-app com.example.mygame "My Game"
cd cordova-app

# 2. Add platforms
npx cordova platform add ios       # macOS only
npx cordova platform add android

# 3. From your melonJS project, build into dist/
#    (run this from the melonJS project root)
npm run build

# 4. Copy the built bundle into Cordova's www folder
rm -rf cordova-app/www/*
cp -R dist/* cordova-app/www/

Re-run steps 3 and 4 after every code change. You can wire it into an npm script for convenience:

{
  "scripts": {
    "build:cordova": "npm run build && rm -rf cordova-app/www/* && cp -R dist/* cordova-app/www/"
  }
}

Run on a device or emulator

cd cordova-app
npx cordova run ios       # iOS Simulator (or attached device)
npx cordova run android   # Android emulator (or attached device)

# or, build only:
npx cordova build ios
npx cordova build android

For physical iOS devices you'll need to open the platforms/ios/*.xcworkspace in Xcode and sign with your developer team. Android signing is handled by cordova-android's default debug keystore for dev builds.

Lifecycle and back-button

Cordova exposes lifecycle events via document events (not a JS plugin like @capacitor/app). The relevant ones for a game:

document.addEventListener("deviceready", () => {
    // safe to start the game now
}, false);

document.addEventListener("pause", () => {
    state.pause(true);   // also pause audio
}, false);

document.addEventListener("resume", () => {
    state.resume(true);
}, false);

document.addEventListener("backbutton", (evt) => {
    evt.preventDefault();
    state.change(state.MENU);   // or app.exitApp() to quit
}, false);

melonJS's built-in pauseOnVisibility (default true) already handles background/foreground via document.visibilitychange, so the explicit pause / resume listeners are only needed if you also want to pause audio explicitly.

Notes

  • No melonJS-specific Cordova plugin. Unlike the Capacitor path, there's no @melonjs/cordova-plugin — the lifecycle / back-button wiring is just a few addEventListener calls (see above).
  • Plugin ecosystem. Cordova has a long-running plugin registry at cordova.apache.org/plugins for camera, filesystem, in-app purchases, etc. They install via cordova plugin add <name>.
  • iOS WKWebView vs UIWebView. Modern Cordova (12.x+) uses WKWebView by default — older guides referencing UIWebView are out of date.
  • Asset paths. Cordova serves from file:// on most platforms — use relative paths in your bundler config.

See also

Clone this wiki locally