/pixijs-migration-v8

name: pixijs-migration-v8
description: "Use this skill when upgrading to PixiJS v8 from v7 or diagnosing broken v7 code after an upgrade. Covers async app.init, single pixi.js package (deprecated @pixi/* sub-packages), Graphics shape-then-fill, BaseTexture → TextureSource, shader/uniform rework, ParticleContainer+Particle, constructor options objects, DisplayObject removal, settings/utils removal, Ticker signature, events rewrite. Triggers on: migrate v7, v8 breaking changes, @pixi/ import, DisplayObject, beginFill, endFill, cacheAsBitmap, BaseTexture, deprecated."
license: MIT

This skill is a breaking-change checklist for bringing a v7 codebase up to v8. Work top-down through the categories; the list maps each v7 pattern to its v8 replacement.

Quick Start

Install the single package, then port in this order: imports → Application init → Graphics → Text → events → shaders/filters → cleanup.

const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

const g = new Graphics()
  .rect(0, 0, 100, 100)
  .fill({ color: 0xff0000 })
  .stroke({ width: 2, color: 0x000000 });
app.stage.addChild(g);

**Related skills:** `pixijs-application` (async init), `pixijs-scene-graphics` (new fill/stroke API), `pixijs-custom-rendering` (shader rework), `pixijs-scene-text` (Text constructor changes), `pixijs-performance` (destroy patterns).

Migration Checklist: v7 to v8

Work through each category. Each item shows the expected v8 pattern and the v7 pattern that must be replaced.

Initialization

**Async app.init()** -- Expected:

const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

Fail: passing options to `new Application({...})` and using synchronously.

**app.canvas replaces app.view** -- `app.view` emits a deprecation warning.

**Application type parameter** -- Expected: `new Application<Renderer<HTMLCanvasElement>>()`. Fail: `new Application<HTMLCanvasElement>()`.

Imports

**Single package** -- Expected:

import { Sprite, Application, Assets, Graphics } from "pixi.js";

Fail: importing from any of the deprecated v7 core `@pixi/*` sub-packages (see list below). Supplemental packages like `@pixi/sound` are still valid and should continue to be used.

Deprecated `@pixi/*` packages (never use, any version): `@pixi/accessibility`, `@pixi/app`, `@pixi/assets`, `@pixi/compressed-textures`, `@pixi/core`, `@pixi/display`, `@pixi/events`, `@pixi/extensions`, `@pixi/extract`, `@pixi/filter-alpha`, `@pixi/filter-blur`, `@pixi/filter-color-matrix`, `@pixi/filter-displacement`, `@pixi/filter-fxaa`, `@pixi/filter-noise`, `@pixi/graphics`, `@pixi/mesh`, `@pixi/mesh-extras`, `@pixi/mixin-cache-as-bitmap`, `@pixi/mixin-get-child-by-name`, `@pixi/mixin-get-global-position`, `@pixi/particle-container`, `@pixi/prepare`, `@pixi/sprite`, `@pixi/sprite-animated`, `@pixi/sprite-tiling`, `@pixi/spritesheet`, `@pixi/text`, `@pixi/text-bitmap`, `@pixi/text-html`.

**Custom builds** -- Set `skipExtensionImports: true` and import only needed extensions:

import "pixi.js/graphics";
import "pixi.js/text";
import "pixi.js/events";
import { Application } from "pixi.js";
await app.init({ skipExtensionImports: true });

Note: `manageImports: false` is still accepted but `@deprecated since 8.1.6`; prefer `skipExtensionImports: true`.

**Extensions not auto-imported** (require explicit import even with default auto-imports enabled): `pixi.js/advanced-blend-modes`, `pixi.js/unsafe-eval`, `pixi.js/prepare`, `pixi.js/math-extras`, `pixi.js/dds`, `pixi.js/ktx`, `pixi.js/ktx2`, `pixi.js/basis`.

**Community filters** -- Expected: `import { AdjustmentFilter } from 'pixi-filters/adjustment'`. Fail: `@pixi/filter-adjustment`.

Graphics API

**Shape-then-fill** -- Expected:

const g = new Graphics().rect(50, 50, 100, 100).fill(0xff0000);

Fail: `beginFill(0xff0000).drawRect(50, 50, 100, 100).endFill()`.

**Renamed shape methods:**

| v7 | v8 | | -------------------- | ------------- | | `drawRect` | `rect` | | `drawCircle` | `circle` | | `drawEllipse` | `ellipse` | | `drawPolygon` | `poly` | | `drawRoundedRect` | `roundRect` | | `drawStar` | `star` | | `drawRegularPolygon` | `regularPoly` | | `drawRoundedPolygon` | `roundPoly` | | `drawRoundedShape` | `roundShape` | | `drawChamferRect` | `chamferRect` | | `drawFilletRect` | `filletRect` |

**Fill replaces beginFill/beginTextureFill** -- Expected:

graphics
  .rect(0, 0, 100, 100)
  .fill({ texture: Texture.WHITE, alpha: 0.5, color: 0xff0000 });

Fail: `beginFill(color, alpha)` or `beginTextureFill({ texture, alpha, color })`.

**Stroke replaces lineStyle** -- Expected:

graphics.rect(0, 0, 100, 100).fill("blue").stroke({ width: 2, color: "white" });

Fail: `lineStyle(2, 'white')` or `lineTextureStyle({ texture, width, color })`.

**Holes use cut()** -- Expected:

graphics.rect(0, 0, 100, 100).fill(0x00ff00).circle(50, 50, 20).cut();

Fail: `beginHole()` / `endHole()`.

**GraphicsContext replaces GraphicsGeometry** -- Expected:

const context = new GraphicsContext().rect(0, 0, 100, 100).fill(0xff0000);
const g1 = new Graphics(context);
const g2 = new Graphics(context);

Fail: `new Graphics(graphics.geometry)`.

Text

**Options object constructor** -- Expected:

const text = new Text({ text: "Hello", style: { fontSize: 24 } });
const bmp = new BitmapText({ text: "Hello", style: { fontFamily: "MyFont" } });
const html = new HTMLText({ text: "<b>Hello</b>", style: { fontSize: 24 } });

Fail: `new Text('Hello', { fontSize: 24 })` (positional args).

**Bitmap font loading** -- Must `import 'pixi.js/text-bitmap'` before `Assets.load('font.fnt')`.

Sprites / Mesh

**Texture.from no longer loads URLs** -- Must call `await Assets.load('imag