pixijs/pixijs-environments

DOMAdapter abstracts every piece of DOM access PixiJS does (canvas creation, Image loading, fetch, XML parsing) so the library can run in non-browser contexts. Call DOMAdapter.set(...) before app.init() to swap in a different adapter.

Quick Start

// worker.ts — OffscreenCanvas posted from main thread
DOMAdapter.set(WebWorkerAdapter);

self.onmessage = async (event) => {
  const app = new Application();
  await app.init({
    canvas: event.data.canvas,
    width: 800,
    height: 600,
  });
};

For CSP contexts that block unsafe-eval, import the polyfill before any renderer init:

import "pixi.js/unsafe-eval";

Related skills: pixijs-application (standard browser init), pixijs-migration-v8 (settings removal, adapter changes).

Core Patterns

Web Worker with OffscreenCanvas

Transfer an OffscreenCanvas from the main thread, then initialize PixiJS in the worker:

// main.ts
const canvas = document.createElement("canvas");
canvas.width = 800;
canvas.height = 600;
document.body.appendChild(canvas);

const offscreen = canvas.transferControlToOffscreen();
const worker = new Worker("worker.ts", { type: "module" });
worker.postMessage({ canvas: offscreen }, [offscreen]);

// worker.ts
import { Application, DOMAdapter, WebWorkerAdapter } from "pixi.js";

DOMAdapter.set(WebWorkerAdapter);

self.onmessage = async (event) => {
  const app = new Application();
  await app.init({
    canvas: event.data.canvas,
    width: 800,
    height: 600,
  });
};

DOMAdapter.set(WebWorkerAdapter) must happen before new Application(). The WebWorkerAdapter uses OffscreenCanvas instead of document.createElement('canvas') and @xmldom/xmldom for XML parsing.

Features that do not work inside a Web Worker (no DOM access):

• DOMContainer — there is no real DOM node to overlay.
• AccessibilitySystem — depends on live DOM focus and screen reader hooks.
• FontFace loading via the Font Loading API — use pre-converted bitmap fonts (BitmapFont.install or .fnt assets) instead.

Environment-specific subpath imports

Instead of importing pixi.js, you can pull in a curated bundle for each environment:

import "pixi.js/browser"; // accessibility, dom, events, spritesheet, rendering, filters
import "pixi.js/webworker"; // spritesheet, rendering, filters (no DOM-only modules)

pixi.js/webworker deliberately omits accessibility, dom, and events because they require the DOM. Use these subpath entries when you want static, synchronous module registration instead of relying on loadEnvironmentExtensions to dynamic-import the right set at renderer init.

loadEnvironmentExtensions

import { loadEnvironmentExtensions } from "pixi.js";

await loadEnvironmentExtensions(false); // false = load defaults; true = skip

loadEnvironmentExtensions(skip) replaces the deprecated autoDetectEnvironment helper (since 8.1.6). Pass true to opt out of auto-loading the default browser extensions when you are bootstrapping a custom environment. autoDetectEnvironment(add) still exists as a shim that forwards to loadEnvironmentExtensions(!add).

CSP-compliant setup

PixiJS uses new Function() internally for shader compilation and uniform syncing. In Content Security Policy environments that block unsafe-eval, import the polyfill:

import "pixi.js/unsafe-eval";
import { Application } from "pixi.js";

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

The pixi.js/unsafe-eval import replaces eval-based code generation with static polyfills for shader sync, UBO sync, uniform sync, and particle buffer updates. The import must come before any PixiJS renderer initialization.

Tension note: The name pixi.js/unsafe-eval is counterintuitive. It does not enable unsafe eval; it removes the need for it. The name refers to the CSP directive it works around.

Custom adapter

For non-standard environments (Node.js, headless testing, SSR), implement the full Adapter interface:

import { DOMAdapter } from "pixi.js";
import type { Adapter } from "pixi.js";
import { createCanvas, Image } from "canvas";
import { DOMParser } from "@xmldom/xmldom";

const HeadlessAdapter: Adapter = {
  createCanvas: (width, height) => createCanvas(width ?? 0, height ?? 0),
  createImage: () => new Image(),
  getCanvasRenderingContext2D: () => CanvasRenderingContext2D,
  getWebGLRenderingContext: () => WebGLRenderingContext,
  getNavigator: () => ({ userAgent: "HeadlessAdapter", gpu: null }),
  getBaseUrl: () => "file://",
  getFontFaceSet: () => null,
  fetch: (url, options) => fetch(url, options),
  parseXML: (xml) => new DOMParser().parseFromString(xml, "text/xml"),
};

DOMAdapter.set(HeadlessAdapter);

The Adapter interface requires these methods: createCanvas, createImage, getCanvasRenderingContext2D, getWebGLRenderingContext, getNavigator, getBaseUrl, getFontFaceSet, fetch, parseXML.

Checking the current adapter

import { DOMAdapter } from "pixi.js";

const adapter = DOMAdapter.get();
const canvas = adapter.createCanvas(256, 256);
const img = adapter.createImage();

DOMAdapter.get() returns whatever adapter is currently set. Use this for any DOM access within PixiJS-adjacent code instead of calling document or Image directly.

Common Mistakes

[CRITICAL] Not setting adapter before app.init()

Wrong:

const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // too late; adapter already read during init

Correct:

DOMAdapter.set(WebWorkerAdapter);
const app = new Application();
await app.init({ width: 800, height: 600 });

DOMAdapter.set() must be called before app.init() in non-browser environments. PixiJS reads the adapter during app.init() when the renderer is created. new Application() itself only creates the stage Container and does not read the adapter.

[HIGH] Using document or Image directly

Wrong:

const img = new Image();
img.src = "texture.png";

Correct:

import { DOMAdapter } from "pixi.js";

const img = DOMAdapter.get().createImage();
img.src = "texture.png";

All DOM access in PixiJS goes through DOMAdapter. Direct use of document, Image, or other browser globals breaks Web Worker and SSR compatibility.

[HIGH] CSP unsafe-eval import name confusion

Wrong:

// CSP environment, omitting the import
import { Application } from "pixi.js";
// Throws: "Current environment does not allow unsafe-eval,
// please use pixi.js/unsafe-eval module to enable support."

Correct:

import "pixi.js/unsafe-eval";
import { Application } from "pixi.js";

The pixi.js/unsafe-eval import removes the need for eval() / new Function() in shader compilation. Despite the name suggesting it enables unsafe eval, it does the opposite: it installs static polyfills so PixiJS works under strict CSP.

PixiJS detects CSP blocking at renderer init and throws the error above. The browser may also log its own CSP violation before PixiJS reports; both point to the same fix.

[HIGH] Using old settings.ADAPTER pattern

Wrong:

import { settings, WebWorkerAdapter } from "pixi.js";
settings.ADAPTER = WebWorkerAdapter;

Correct:

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

The settings object was removed in v8. All adapter configuration uses DOMAdapter.set().

API Reference

• DOMAdapter
• BrowserAdapter
• WebWorkerAdapter
• autoDetectEnvironment
• loadEnvironmentExtensions