Phaser.js for Web Games - Complete Learning Guide

Guides / Phaser.js for Web Games / Phaser.js Introduction: Getting Started with Web Game Development

Phaser.js Introduction - Getting Started with Web Game Development

===================================================================

Phaser is a free, open-source 2D game framework that runs in the browser. You write JavaScript (or TypeScript), and Phaser handles the game loop, rendering to Canvas or WebGL, loading assets, physics, input, and audio. If you want to build playable games that work on the web without installing an engine, Phaser is one of the most popular choices.

This chapter gives you a clear picture of what Phaser is, when it fits your project, and how to run your first Phaser game locally.

Who this chapter is for

-----------------------

Web developers who want to add a game or interactive experience to a site
Game devs exploring browser-based tools for prototypes or full releases
Anyone learning game loops, sprites, and scenes in a JavaScript environment

By the end, you will know what Phaser does well, how it is structured, and the minimal setup needed to see a running game in the browser.

What Phaser is (and is not)

---------------------------

Phaser is:

A 2D game framework for HTML5 games (Canvas or WebGL)
Framework, not engine – You write code; there is no visual editor like Unity or Godot
JavaScript/TypeScript – Works with npm, bundlers (Vite, Webpack), or script tags
Scene-based – You organize your game into scenes (menu, level, game over, etc.)
Feature-rich – Built-in support for sprites, tilemaps, arcade physics, Matter.js, audio, and more

Phaser is not:

A 3D engine (for 3D you would look at Three.js, Babylon.js, or similar)
A no-code tool – You write logic in code
A desktop or mobile native engine – It targets the browser; packaging for app stores is possible with tools like Capacitor or Cordova

When to use Phaser

------------------

Phaser fits well when:

You want browser games that run on most devices without installs
You are comfortable with JavaScript or TypeScript
Your game is 2D (platformer, puzzle, top-down, card game, etc.)
You want a mature ecosystem – lots of examples, plugins, and community

It is less ideal when:

You need a drag-and-drop or visual editor – consider Construct, GDevelop, or Godot exported to web
You need heavy 3D – use a 3D-focused library instead
You need native console or mobile app as the primary target – a native engine may be simpler

How Phaser is structured

-------------------------

A minimal Phaser game has:

Game config – Canvas size, renderer (Canvas or WebGL), default scene, scale mode, etc.
Scenes – Each scene has lifecycle methods: <code>preload()</code>, <code>create()</code>, and <code>update()</code>. You load assets in <code>preload</code>, create objects in <code>create</code>, and run per-frame logic in <code>update</code>.
Game objects – Sprites, text, tiles, groups. You add them to a scene and Phaser draws and updates them.

You typically create one <code>Phaser.Game</code> instance and register your scenes. Phaser then runs the active scene’s loop and handles input, physics, and rendering.

Getting Phaser

--------------

You can use Phaser in two main ways:

Option A – npm (recommended for real projects)

npm init -y
npm install phaser

Then in your entry file (e.g. <code>main.js</code> or <code>main.ts</code>):

import Phaser from 'phaser';
// Your scene classes and game config

Use a bundler (e.g. Vite) to build for the browser.

Option B – Script tag (quick tests)

Include the Phaser build from a CDN:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/phaser.min.js"></script>

Then write your config and scenes in another script tag or file. No build step, but less convenient for large projects.

Your first “Hello Phaser” scene

-------------------------------

A minimal example that opens a window, creates a scene, and shows text:

const config = {
  type: Phaser.AUTO,
  width: 800,
  height: 600,
  parent: 'game-container',
  scene: {
    create() {
      this.add.text(400, 300, 'Hello Phaser', {
        fontSize: 32,
        color: '#ffffff'
      }).setOrigin(0.5);
    }
  }
};

const game = new Phaser.Game(config);

<code>type: Phaser.AUTO</code> – Use WebGL if available, otherwise Canvas
<code>width</code> / <code>height</code> – Size of the game canvas
<code>parent</code> – ID of the HTML element that will hold the canvas (you need <code><div id="game-container"></div></code> in your HTML)
<code>scene</code> – Inline scene with a <code>create()</code> method where you add a text object at the center

If you run this in a page that has a <code><div id="game-container"></div></code>, you will see “Hello Phaser” in the middle of the canvas.

Pro tip

-------

Keep the <a href="https://photonstorm.github.io/phaser3-docs/">Phaser 3 API docs</a> and <a href="https://labs.phaser.io/">official examples</a> open while learning. Most concepts (scenes, sprites, physics, input) are easier to grasp by tweaking an example.

Common mistakes to avoid

-------------------------

Forgetting the parent element – If <code>parent</code> does not match an ID in your HTML, the canvas may not appear or may be placed incorrectly.
Using a scene without <code>create()</code> – At least <code>create()</code> is required for the scene to do something visible; <code>preload()</code> and <code>update()</code> are optional.
Assuming Node.js APIs in the browser – Phaser runs in the browser; do not use <code>require('fs')</code> or other Node-only APIs unless you are in a build script.

Troubleshooting

---------------

Blank or black screen

Check the browser console for errors.
Ensure the DOM element with the ID you passed as <code>parent</code> exists before <code>new Phaser.Game(config)</code> runs (e.g. put your script at the end of <code><body></code> or run after <code>DOMContentLoaded</code>).

Canvas too big or too small

Adjust <code>width</code> and <code>height</code> in the config, or use scale options (e.g. <code>scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH }</code>) to fit the container.

“Phaser is not defined”

If using a script tag, ensure the Phaser script loads before your game script. If using a bundler, ensure you import Phaser and that the bundle is loaded in the page.

What’s next

-----------

In the next chapter you will set up a small project (with npm and a dev server or with script tags), create a proper scene class, and run the game so you can iterate quickly. You will also see where to put assets and how to load them in the next chapters.