pixijs-environments

Name: pixijs-environments
Author: pixijs

2.8kinstalls15forks

How to install pixijs-environments?

pixijs/pixijs-skills/pixijs-environments

$npx -y skills add pixijs/pixijs-skills --skill pixijs-environments

Installs into the current project.

Summary

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, Br

Files · 1

View on GitHub

SKILL.md

1	`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.
2
3	## Quick Start
4
5	```ts
6	// worker.ts — OffscreenCanvas posted from main thread
7	DOMAdapter.set(WebWorkerAdapter);
8
9	self.onmessage = async (event) => {
10	const app = new Application();
11	await app.init({
12	canvas: event.data.canvas,
13	width: 800,
14	height: 600,
15	});
16	};
17	```
18
19	For CSP contexts that block `unsafe-eval`, import the polyfill before any renderer init:
20
21	```ts
22	import "pixi.js/unsafe-eval";
23	```
24
25	Related skills: `pixijs-application` (standard browser init), `pixijs-migration-v8` (settings removal, adapter changes).
26
27	## Core Patterns
28
29	### Web Worker with OffscreenCanvas
30
31	Transfer an OffscreenCanvas from the main thread, then initialize PixiJS in the worker:
32
33	```ts
34	// main.ts
35	const canvas = document.createElement("canvas");
36	canvas.width = 800;
37	canvas.height = 600;
38	document.body.appendChild(canvas);
39
40	const offscreen = canvas.transferControlToOffscreen();
41	const worker = new Worker("worker.ts", { type: "module" });
42	worker.postMessage({ canvas: offscreen }, [offscreen]);
43	```
44
45	```ts
46	// worker.ts
47	import { Application, DOMAdapter, WebWorkerAdapter } from "pixi.js";
48
49	DOMAdapter.set(WebWorkerAdapter);
50
51	self.onmessage = async (event) => {
52	const app = new Application();
53	await app.init({
54	canvas: event.data.canvas,
55	width: 800,
56	height: 600,
57	});
58	};
59	```
60
61	`DOMAdapter.set(WebWorkerAdapter)` must happen before `new Application()`. The WebWorkerAdapter uses `OffscreenCanvas` instead of `document.createElement('canvas')` and `@xmldom/xmldom` for XML parsing.
62
63	Features that do not work inside a Web Worker (no DOM access):
64
65	- `DOMContainer` — there is no real DOM node to overlay.
66	- `AccessibilitySystem` — depends on live DOM focus and screen reader hooks.
67	- `FontFace` loading via the Font Loading API — use pre-converted bitmap fonts (`BitmapFont.install` or `.fnt` assets) instead.
68
69	### Environment-specific subpath imports
70
71	Instead of importing `pixi.js`, you can pull in a curated bundle for each environment:
72
73	```ts
74	import "pixi.js/browser"; // accessibility, dom, events, spritesheet, rendering, filters
75	import "pixi.js/webworker"; // spritesheet, rendering, filters (no DOM-only modules)
76	```
77
78	`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.
79
80	### loadEnvironmentExtensions
81
82	```ts
83	import { loadEnvironmentExtensions } from "pixi.js";
84
85	await loadEnvironmentExtensions(false); // false = load defaults; true = skip
86	```
87
88	`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)`.
89
90	### CSP-compliant setup
91
92	PixiJS uses `new Function()` internally for shader compilation and uniform syncing. In Content Security Policy environments that block `unsafe-eval`, import the polyfill:
93
94	```ts
95	import "pixi.js/unsafe-eval";
96	import { Application } from "pixi.js";
97
98	const app = new Application();
99	await app.init({ width: 800, height: 600 });
100	```
101
102	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.
103
104	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.
105
106	### Custom adapter
107
108	For non-standard environments (Node.js, headless testing, SSR), implement the full Adapter interface:
109
110	```ts
111	import { DOMAdapter } from "pixi.js";
112	import type { Adapter } from "pixi.js";
113	import { createCanvas, Image } from "canvas";
114	import { DOMParser } from "@xmldom/xmldom";
115
116	const HeadlessAdapter: Adapter = {
117	createCanvas: (width, height) => createCanvas(width ?? 0, height ?? 0),
118	createImage: () => new Image(),
119	getCanvasRenderingContext2D: () => CanvasRenderingContext2D,
120	getWebGLRenderingContext: () => WebGLRenderingContext,
121	getNavigator: () => ({ userAgent: "HeadlessAdapter"

People who liked this also viewed

6 picks

Type

pixijs-environments

2.8kinstalls15forks

View on GitHub

How to install pixijs-environments?

pixijs/pixijs-skills/pixijs-environments

$npx -y skills add pixijs/pixijs-skills --skill pixijs-environments

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	`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.
2
3	## Quick Start
4
5	```ts
6	// worker.ts — OffscreenCanvas posted from main thread
7	DOMAdapter.set(WebWorkerAdapter);
8
9	self.onmessage = async (event) => {
10	const app = new Application();
11	await app.init({
12	canvas: event.data.canvas,
13	width: 800,
14	height: 600,
15	});
16	};
17	```
18
19	For CSP contexts that block `unsafe-eval`, import the polyfill before any renderer init:
20
21	```ts
22	import "pixi.js/unsafe-eval";
23	```
24
25	Related skills: `pixijs-application` (standard browser init), `pixijs-migration-v8` (settings removal, adapter changes).
26
27	## Core Patterns
28
29	### Web Worker with OffscreenCanvas
30
31	Transfer an OffscreenCanvas from the main thread, then initialize PixiJS in the worker:
32
33	```ts
34	// main.ts
35	const canvas = document.createElement("canvas");
36	canvas.width = 800;
37	canvas.height = 600;
38	document.body.appendChild(canvas);
39
40	const offscreen = canvas.transferControlToOffscreen();
41	const worker = new Worker("worker.ts", { type: "module" });
42	worker.postMessage({ canvas: offscreen }, [offscreen]);
43	```
44
45	```ts
46	// worker.ts
47	import { Application, DOMAdapter, WebWorkerAdapter } from "pixi.js";
48
49	DOMAdapter.set(WebWorkerAdapter);
50
51	self.onmessage = async (event) => {
52	const app = new Application();
53	await app.init({
54	canvas: event.data.canvas,
55	width: 800,
56	height: 600,
57	});
58	};
59	```
60
61	`DOMAdapter.set(WebWorkerAdapter)` must happen before `new Application()`. The WebWorkerAdapter uses `OffscreenCanvas` instead of `document.createElement('canvas')` and `@xmldom/xmldom` for XML parsing.
62
63	Features that do not work inside a Web Worker (no DOM access):
64
65	- `DOMContainer` — there is no real DOM node to overlay.
66	- `AccessibilitySystem` — depends on live DOM focus and screen reader hooks.
67	- `FontFace` loading via the Font Loading API — use pre-converted bitmap fonts (`BitmapFont.install` or `.fnt` assets) instead.
68
69	### Environment-specific subpath imports
70
71	Instead of importing `pixi.js`, you can pull in a curated bundle for each environment:
72
73	```ts
74	import "pixi.js/browser"; // accessibility, dom, events, spritesheet, rendering, filters
75	import "pixi.js/webworker"; // spritesheet, rendering, filters (no DOM-only modules)
76	```
77
78	`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.
79
80	### loadEnvironmentExtensions
81
82	```ts
83	import { loadEnvironmentExtensions } from "pixi.js";
84
85	await loadEnvironmentExtensions(false); // false = load defaults; true = skip
86	```
87
88	`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)`.
89
90	### CSP-compliant setup
91
92	PixiJS uses `new Function()` internally for shader compilation and uniform syncing. In Content Security Policy environments that block `unsafe-eval`, import the polyfill:
93
94	```ts
95	import "pixi.js/unsafe-eval";
96	import { Application } from "pixi.js";
97
98	const app = new Application();
99	await app.init({ width: 800, height: 600 });
100	```
101
102	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.
103
104	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.
105
106	### Custom adapter
107
108	For non-standard environments (Node.js, headless testing, SSR), implement the full Adapter interface:
109
110	```ts
111	import { DOMAdapter } from "pixi.js";
112	import type { Adapter } from "pixi.js";
113	import { createCanvas, Image } from "canvas";
114	import { DOMParser } from "@xmldom/xmldom";
115
116	const HeadlessAdapter: Adapter = {
117	createCanvas: (width, height) => createCanvas(width ?? 0, height ?? 0),
118	createImage: () => new Image(),
119	getCanvasRenderingContext2D: () => CanvasRenderingContext2D,
120	getWebGLRenderingContext: () => WebGLRenderingContext,
121	getNavigator: () => ({ userAgent: "HeadlessAdapter"

People who liked this also viewed

6 picks

Type