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
disable-model-invocation	true

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('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

Sprite no longer auto-detects texture UV changes -- If you modify a texture's frame after creation, call texture.update() to recalculate UVs, then call sprite.onViewUpdate() to refresh the sprite. Both calls are required in this order. Updating source data (e.g. video textures) is still automatic.

texture.frame.width = texture.frame.width / 2;
texture.update(); // recalculate texture UVs first
sprite.onViewUpdate(); // then refresh the sprite's display

Mipmaps -- BaseTexture.mipmap renamed to autoGenerateMipmaps. For RenderTextures, you must manually update mipmaps:

const rt = RenderTexture.create({
  width: 100,
  height: 100,
  autoGenerateMipmaps: true,
});
renderer.render({ target: rt, container: scene });
rt.source.updateMipmaps();

Adapters

DOMAdapter replaces settings.ADAPTER -- Expected:

import { DOMAdapter, WebWorkerAdapter } from "pixi.js";
DOMAdapter.set(WebWorkerAdapter);
DOMAdapter.get().createCanvas();

Fail: settings.ADAPTER = WebWorkerAdapter; settings.ADAPTER.createCanvas();.

Built-in adapters: BrowserAdapter (default), WebWorkerAdapter (for web workers).

Other

DisplayObject removed -- Container is the base class. class MyObj extends DisplayObject fails.

Leaf nodes cannot have children -- Sprite, Graphics, Mesh, Text are leaf nodes. Wrap in Container.

Renamed properties (old names still exist as deprecated aliases with warnings):

• container.name -> container.label
• container.cacheAsBitmap = true -> container.cacheAsTexture(true)