Phaser 4 (RC-5), Next.js v16 App Router, React v.19 deprecates forwardRef, code cleanup, other fixes

[ospira]

Further iterating on this: #3

Since these templates and requested features (#5) are not a current priority at the moment for the very busy core team, I thought I would help out especially as the previous PR on this was helpful to others despite no merge. As mentioned in the previous PR, it is good to give back when the core team gives us so much.

Updates (from the previous update - see earlier PR #3 linked at the top):

1. Uses Phaser 4
2. Next.js 16
3. Better code, cleaner app router, ships with latest Next.js (16) defaults
4. Includes default prettier for ease of use with vscode

---

Note

Upgrades to Next.js 16 (App Router), React 19 and Phaser 4, refactors the React–Phaser integration and scenes, and adds modern lint/format/build configs.

• Framework/Runtime:
  • Upgrade to next@16 with App Router (src/app/*), remove pages/*, add layout.tsx and page.tsx.
  • Upgrade to react@19/react-dom@19.
  • Node engine set to >=24.
• Game/Phaser:
  • Upgrade to phaser@4.0.0-rc.5.
  • Introduce GameScene base class (src/game/scenes/common/GameScene.ts) and refactor MainMenu, Game, GameOver to use it and the shared EventBus.
  • Reorganize loaders (Boot, Preloader) under scenes/loaders; add utils/config for shared dimensions.
• React–Phaser Bridge:
  • Replace forwardRef pattern with typed ref prop and onChangeScene callback; dynamic-load PhaserGame with ssr: false.
  • Update App.tsx to manage scene changes and sprite movement via the new API.
• Tooling/Config:
  • Add flat ESLint config (eslint.config.mjs), Prettier (.prettierrc), Tailwind/PostCSS (postcss.config.mjs).
  • Replace next.config.mjs with typed next.config.ts.
  • Expand .gitignore; add scripts (start, lint, *-nolog).
  • Update dependencies and add pnpm-lock.yaml; remove package-lock.json.

^{Written by Cursor Bugbot for commit f08967d. This will update automatically on new commits. Configure here.}

[cursor]

This PR is being reviewed by Cursor Bugbot

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[cursor]

Bug: React ref Conflict Halts Component Operations.

The component uses ref as a regular prop name instead of using forwardRef. In React, ref is a reserved prop that won't be passed to the component as a regular prop. When <PhaserGame ref={phaserRef} /> is used in App.tsx, the ref parameter will be undefined inside the component, causing all ref operations to fail and breaking the game initialization and scene management functionality.

 

[ospira]

hallucination: https://react.dev/reference/react/forwardRef