AGENT SKILL

pixijs-environments

Use this skill when running PixiJS v8 outside a standard browser: Web Workers, OffscreenCanvas, Node/SSR, or CSP-restricted contexts. Covers DOMAdapter.set, BrowserAdapter, WebWorkerAdapter, custom Adapter interface, pixi.js/unsafe-eval for strict CSP. Triggers on: DOMAdapter, BrowserAdapter, WebWorkerAdapter, Web Worker, OffscreenCanvas, Node, headless, SSR, CSP, unsafe-eval, Adapter.

License 许可
MIT
最近更新
2026-07-18
Stars
★ 0
Forks
1

01 前言 Front Matter

name
pixijs-environments
license
MIT
description
Use this skill when running PixiJS v8 outside a standard browser: Web Workers, OffscreenCanvas, Node/SSR, or CSP-restricted contexts. Covers DOMAdapter.set, BrowserAdapter, WebWorkerAdapter, custom Adapter interface, pixi.js/unsafe-eval for strict CSP. Triggers on: DOMAdapter, BrowserAdapter, WebWorkerAdapter, Web Worker, OffscreenCanvas, Node, headless, SSR, CSP, unsafe-eval, Adapter.

03 SKILL.md 正文

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

04 同仓库更多 Skills

om-scogo
om-scogo/skillsh-scraper

arxiv-search

Search arXiv physics, math, and computer science preprints using natural language queries. Powered by Valyu semantic search.

★ 0
om-scogo
om-scogo/skillsh-scraper

arxiv-search

Search arXiv physics, math, and computer science preprints using natural language queries. Powered by Valyu semantic search.

★ 0
om-scogo
om-scogo/skillsh-scraper

working-with-legacy-code

Safely change and test untested codebases using Feathers' "Working Effectively with Legacy Code". Use when the user mentions "legacy code", "no tests", "untested codebase", "how do I test this", "seams", "characterization tests", "golden master", "sprout method", "afraid to change this code", "monster method", "dependency breaking", or "inherited a messy codebase". Also trigger when changing code without tests safely, getting a class under test when constructors, statics, or singletons block it, adding features to tangled modules, or planning incremental test coverage for an old codebase. Covers the legacy-code change algorithm, seams, characterization tests, sprout/wrap, and dependency-breaking techniques. For refactoring code that already has tests, see refactoring-patterns. For day-to-day code quality, see clean-code.

★ 0
om-scogo
om-scogo/skillsh-scraper

working-with-legacy-code

Safely change and test untested codebases using Feathers' "Working Effectively with Legacy Code". Use when the user mentions "legacy code", "no tests", "untested codebase", "how do I test this", "seams", "characterization tests", "golden master", "sprout method", "afraid to change this code", "monster method", "dependency breaking", or "inherited a messy codebase". Also trigger when changing code without tests safely, getting a class under test when constructors, statics, or singletons block it, adding features to tangled modules, or planning incremental test coverage for an old codebase. Covers the legacy-code change algorithm, seams, characterization tests, sprout/wrap, and dependency-breaking techniques. For refactoring code that already has tests, see refactoring-patterns. For day-to-day code quality, see clean-code.

★ 0
om-scogo
om-scogo/skillsh-scraper

web-typography

Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", "typographic scale", or "the text is hard to read". Also trigger when choosing between system fonts and web fonts, optimizing font-loading performance, or designing readable long-form content. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.

★ 0
om-scogo
om-scogo/skillsh-scraper

web-typography

Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", "type hierarchy", "variable fonts", "FOUT/FOIT", "typographic scale", or "the text is hard to read". Also trigger when choosing between system fonts and web fonts, optimizing font-loading performance, or designing readable long-form content. Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.

★ 0