Pixijs Migration V8

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:

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('image.png') first, then Texture.from('image.png').

NineSliceSprite replaces NineSlicePlane -- Expected:

const ns = new NineSliceSprite({
  texture,
  leftWidth: 10,
  topHeight: 10,
  rightWidth: 10,
  bottomHeight: 10,
});

Mesh renames: SimpleMesh -> MeshSimple, SimplePlane -> MeshPlane, SimpleRope -> MeshRope. All use options objects.

MeshGeometry options -- Expected:

const geom = new MeshGeometry({
  positions: vertices,
  uvs,
  indices,
  topology: "triangle-list",
});

Fail: new MeshGeometry(vertices, uvs, indices).

ParticleContainer uses Particle -- Expected:

const container = new ParticleContainer({
  boundsArea: new Rectangle(0, 0, 800, 600),
});
const particle = new Particle(texture);
container.addParticle(particle);

Fail: container.addChild(new Sprite(texture)).

Events

eventMode replaces interactive -- Expected:

sprite.eventMode = "static";
sprite.cursor = "pointer";
sprite.on("pointertap", () => {
  /* handle */
});

Legacy: sprite.interactive = true; (still works as an alias for eventMode = 'static', but prefer the explicit form).

Default eventMode is 'passive' (no events). Must set 'static' or 'dynamic' explicitly.

Ticker callback -- Expected:

app.ticker.add((ticker) => {
  bunny.rotation += ticker.deltaTime;
});

Broken: app.ticker.add((dt) => { bunny.rotation += dt; }) -- compiles but dt is a Ticker object, not a number. Coerces to NaN, silently corrupting rotation.

updateTransform removed -- Use this.onRender = this._onRender.bind(this) in constructor instead.

Shaders

Shader.from uses options -- Expected:

const shader = Shader.from({
  gl: { vertex: vertexSrc, fragment: fragmentSrc },
  resources: {
    myUniforms: new UniformGroup({ uTime: { value: 0, type: "f32" } }),
  },
});

Fail: Shader.from(vertex, fragment, uniforms).

Filter constructor -- Expected:

const filter = new Filter({
  glProgram: GlProgram.from({ fragment, vertex }),
  resources: { filterUniforms: { uTime: { value: 0, type: "f32" } } },
});

Fail: new Filter(vertex, fragment, { uTime: 0 }).

Uniforms require type -- new UniformGroup({ uTime: { value: 1, type: 'f32' } }). Fail: new UniformGroup({ uTime: 1 }).

Textures are resources, not uniforms -- Pass as top-level resource entries (texture.source, texture.style), not inside UniformGroup.

Textures