Phaser: main points at source, the browser field points at 8.23 MB, and v4 replaced the renderer

The main field points at source, so a plain require pulls the unbundled tree

The package manifest has two resolution paths and they do not agree. The main field is ./src/phaser.js, which is source. The exports map is a separate, modern declaration with three cases: types pointing at ./types/phaser.d.ts, import pointing at ./dist/phaser.esm.js, require pointing at ./dist/phaser.js, and default falling back to the ESM build. A tool that honours exports gets a distribution bundle. A tool that falls back to the legacy main field gets the source tree, which means the untranspiled src directory and whatever it expects to find alongside it. That difference is invisible in application code, since both spellings import the same module, and it shows up as a build that suddenly needs a bundler, a transform step or a source map it did not need last week. If you are integrating Phaser into an existing toolchain, check which of the two it resolves before you conclude that the package is broken.

Over 84% of the 8.23 MB file is documentation, and the browser field points at it

The size section handles the question directly. If you open phaser.js and see a file over 8 MB, the reason given is that over 84% of it is inline documentation, in the form of JSDoc comments, type annotations and detailed method descriptions, and that it is there for your IDE rather than for your players. The three figures given are 8.23 MB raw for phaser.js with docs, 1.29 MB raw and 345 KB with standard gzip compression for the full phaser.min.js, and 1.18 MB raw and 313 KB compressed for phaser-arcade.min.js. The detail worth noticing is in the manifest rather than the table. The browser field is ./dist/phaser.js, which is the documented build, not the minified one. So a bundler that follows the browser field hands you 8.23 MB of raw source unless your own pipeline minifies afterwards. The page also notes you can go smaller by tweaking build settings to exclude features your game does not need, which is the difference between the full and arcade builds and the reason the arcade figure exists.

The TypeScript definitions are generated from the same JSDoc that bloats the file

Those two facts are the same fact. The manifest ships types at ./types/phaser.d.ts and calls them first-class, and the build scripts show where they come from:

"build-tsgen": "cd scripts/tsgen && tsc",
"tsgen": "cd scripts/tsgen && jsdoc -c jsdoc-tsd.conf.json",
"test-ts": "cd scripts/tsgen/test && tsc --build tsconfig.json > output.txt 2>&1",

Type generation is a JSDoc run with a specific configuration file, followed by a TypeScript compile of the generator itself and a separate compile of the generated declarations as a test. That explains the 84% figure precisely: the documentation is not a build-time comment that gets stripped and discarded, it is the input to the type pipeline, which is why the same comments ship inside the runtime file and why the TypeScript experience is good without anyone hand-writing declarations. It also means the two are coupled. The type definitions are a downstream artifact of a documentation run, so a change to how comments are written or how the generator is configured can affect the published types, and the only guard visible here is a test-ts compile of the output.

npm publish --tag beta republishes whatever version the manifest already carries

Publishing is two scripts long:

"beta": "npm publish --tag beta",
"dist": "webpack --config config/webpack.dist.config.js",

The beta script adds a dist tag and nothing else. It does not compute a prerelease version, does not read a branch name and does not derive a suffix. The version in the manifest is what gets published under the beta tag, so a beta release of an unedited manifest puts the current stable version number, 4.2.1, on the beta channel, where it sits alongside the stable artefact of the same version. Preparing a beta is therefore a manual step: someone edits the version field first. The same manifest also carries a release field, currently the codename Giedi, which means each tagged release has a name that lives in the file rather than in a release note. Neither detail is wrong, and neither is documented on the README page, but both are the kind of thing you want to know before you pin a version from the beta channel.

Version 4 replaced the render pipeline, so a v3 upgrade is a migration project

The v4 section is blunt about the scale of the change. Phaser 4 is described as a major release built on a brand-new WebGL renderer, with the entire rendering pipeline from v3 replaced by a modern node-based architecture that manages WebGL state properly, handles context loss gracefully and is faster. Then the sentence that matters for an existing project: if you have built games with Phaser 3 the public API is mostly familiar, but under the hood everything has changed. The specifics are concrete. The v3 pipeline system is gone, replaced by render nodes that each handle a single task. Quads use index buffers, which the page says reduces vertex upload costs by a third. Multi-texture batching is smarter and avoids unnecessary batch breaks on mobile. And the system uses just-in-time rendering, so nothing reaches the GPU until it has to. The practical risk is therefore not your game code, which is mostly familiar, but your plugins and any custom render pipeline you wrote against v3 internals.

FX and Masks became one Filter system, and Blend moves 27 blend modes onto the GPU

The second v4 headline is unification. Effects and Masks from v3 are now a single Filter system that can be applied to any game object or any camera, with the stated removal of the old restrictions on which objects support effects. The design rule is what makes them composable: every filter takes an input image and produces an output, usually through a single shader, so all of them are mutually compatible. Masks are now filters too, and a Container full of filtered and masked objects can itself serve as a mask source. The built-in list is long, with Blur, Glow, Shadow, Pixelate, ColorMatrix, Bloom, Vignette and Wipe, plus newer entries including ImageLight for image-based lighting, Blocky for pixel art, GradientMap for palette swaps, Quantize for retro dithering, Key for chroma keying, NormalTools for normal map work, and Blend, which brings all 27 Canvas blend modes to WebGL. Two consequences follow. Configuration written for v3 effects and masks has to be rewritten, and filters that Canvas handled on the CPU now cost you shader time on the GPU.

Every non-web platform arrives through somebody else's wrapper

The reach claim is wide. Games can be built for the web, or as YouTube Playables, Discord Activities, Reddit games and Twitch Overlays, or compiled to iOS, Android, Steam and native apps using third party tools. Read the last clause carefully, because it is doing real work in that sentence. Phaser produces a web game; every native and store destination is mediated by a wrapper that somebody else maintains and that will break on its own schedule. The front-end story has the same shape. The page claims support for over 40 front-end frameworks including React and Vue, and the create-game app offers templates for Vue.js, React, Angular, Next.js, SolidJS, Svelte and Remix against Vite, Rollup, Parcel, Webpack, ESBuild, Import Map and Bun. That is a combinatorial matrix, and the qualifier is that most templates come in both JavaScript and TypeScript versions. So the combination you need may exist only in JavaScript, and the README does not say which.

A Travis config sits in the same tree as a Vitest config and an ESLint 8 style config

The root listing is a small time capsule. There is a .travis.yml, which belongs to a CI era that has largely been replaced, next to a vitest.config.js, which belongs to the current one. Linting is configured through a legacy .eslintrc.json passed explicitly on the command line, with lint running eslint --config .eslintrc.json over src and a lintfix variant adding --fix. The dist directory is committed rather than ignored, which is consistent with a project that ships prebuilt files for CDN use, and the licence file is LICENSE.md with a separate CITATION.cff for academic citation. Version history is split between a CHANGELOG.md at the root and a changelog directory that holds the v4.0 changelog and migration guide the README points to. None of this is broken. It is a working repository with accumulated layers, and the last push on the master branch was on 2026-08-21 with the current release at v4.2.1 from 2026-07-09. The practical note is that the README never describes the test suite, so how to run the tests is something you read from package.json rather than from the documentation.

Editorial conclusion

Phaser fits a browser-first 2D project, in JavaScript or TypeScript, where you want scenes, a loader, Arcade or Matter.js physics, tilemaps and a CDN-friendly single file, and where shipping to a store can go through somebody else's wrapper. It does not fit a v3 codebase you expect to upgrade in place, since the render pipeline was replaced rather than extended, and it does not fit a project that cannot tolerate a bundle whose non-minified form is 8.23 MB. Before you start, check which package entry your bundler resolves, decide between the full and arcade builds deliberately, read the v4 migration guide if you have v3 plugins, and confirm the create-game template you want exists in TypeScript and not only JavaScript.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes