Project Setup

For a sketch or single-file demo, the installation snippet is enough. For a real project, a few decisions will save you weeks.

Bundler

Vite is the recommended starting point — Phaser 4 ships ESM, and Vite handles asset URLs and HMR with no config.

npm create vite@latest my-game -- --template vanilla-ts
cd my-game
npm install phaser

Directory layout

A layout that scales from a jam game to a shipped project:

src/
  main.ts            ← creates the Game and registers scenes
  scenes/
    BootScene.ts     ← preloads the global loading bar assets
    PreloadScene.ts  ← preloads everything else, shows progress
    TitleScene.ts
    GameScene.ts
  objects/           ← reusable GameObject subclasses
  systems/           ← framework-agnostic game logic
  data/              ← typed asset manifests, config tables
public/
  assets/            ← images, audio, tilemaps, atlases

Keep systems/ import-free of Phaser where you can — pure logic is easier to test.

TypeScript

Phaser 4 ships strict types. Use them:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "skipLibCheck": true
  }
}

Hot reload caveats

Vite HMR works for everything outside a running scene. To pick up changes inside a scene, restart the scene with this.scene.restart() or use a dev-only key binding to do so.