To turn a Phaser game into an APK, set your bundler's base path to './', run the production build, check that dist/index.html works from a local server, zip the contents of dist/, and upload the ZIP to an HTML 2 APK builder. Phaser, your scenes and every asset are bundled, so the game runs offline at full WebGL speed.
- Phaser 3 projects on Vite, webpack, Parcel or plain script tags
- Phaser game templates and jam games
- Games using Phaser's Scale Manager (FIT / RESIZE)
- Arcade and Matter physics games
1. Make the build relative
The single most common reason a Phaser APK shows a black screen is an absolute base path: the bundler writes <script src="/assets/index-a1b2.js"> and assets load from /assets/.... Set the base to relative and rebuild:
// vite.config.js
import { defineConfig } from 'vite';
export default defineConfig({
base: './',
build: { assetsInlineLimit: 0 } // keep sprites as files, not base64
});For webpack, set output.publicPath = ''. In your scenes, load assets with paths relative to the page — this.load.image('sky', 'assets/sky.png') — never '/assets/sky.png' or a http://localhost URL.
2. Configure Phaser for phones
const config = {
type: Phaser.AUTO, // WebGL, falls back to canvas
parent: 'game',
backgroundColor: '#0b1b2e',
scale: {
mode: Phaser.Scale.FIT, // or RESIZE for responsive layouts
autoCenter: Phaser.Scale.CENTER_BOTH,
width: 720, height: 1280
},
input: { activePointers: 3 }, // multi-touch
scene: [Boot, Play]
};Add touch-action:none to the canvas and overscroll-behavior:none to html, body so a swipe never scrolls the page. Phaser's sound manager already resumes audio on the first touch.
3. Test, zip and upload
- Run
npx vite preview(ornpx serve dist) and play the build in Chrome's device mode. This is the closest thing to the app on your desktop. - Zip the contents of
dist/soindex.htmlis at the top of the archive. Run it through the ZIP structure checker. - Upload it in the HTML & ZIP to APK Builder app, set the name and icon, build, and install the APK.
Why not Cordova or Capacitor?
They are excellent when you need native plugins — in-app purchases, AdMob, Game Services. They also need Node, the Android SDK, Gradle and Android Studio on your machine, and you maintain the native project yourself. If your Phaser game is self-contained, a cloud HTML 2 APK builder gives the same WebView-based result in minutes. See Capacitor vs HTML to App for the full trade-off.
Phaser to APK — questions
Why is my Phaser APK a black screen?
Almost always absolute paths: the build references /assets/... or a localhost URL. Set base: './' in Vite (publicPath: '' in webpack), rebuild, and load assets with relative paths.
Does Phaser use WebGL inside the APK?
Yes. Phaser.AUTO picks WebGL in Android's WebView exactly as in Chrome, with hardware acceleration.
Can I use Phaser's Scale Manager?
Yes. FIT and RESIZE both work; the canvas fills the app's full-screen WebView and responds to rotation.
How big will a Phaser APK be?
Phaser itself adds about 1 MB minified. With a few MB of sprites and audio, a typical game produces an APK of 8–15 MB.