Skip to main content

Extension template

The extension template is a library project for publishing your own PixiJS plugin, such as a filter, a display object or new methods on existing classes. It uses PixiJS Extension Scripts, a CLI called xs that wraps the build, lint, test, docs and release tools in one dev dependency.

npm create pixi.js@latest my-extension -- --template extension-default

The extension template is TypeScript only. It doesn't use oxlint or oxfmt. xs lint runs ESLint with the PixiJS config instead.

Project structure​

my-extension/
├── examples/
│ └── index.html
├── src/
│ ├── __tests__/
│ │ └── Rectangle.test.ts
│ └── index.ts
├── .gitignore
├── jest.config.mjs
├── LICENSE
├── README.md
├── package.json
└── tsconfig.json

The example in src/index.ts adds an expand method to PixiJS's Rectangle and declares it on the global PixiMixins namespace, so TypeScript knows about the new method:

src/index.ts
import { Rectangle } from "pixi.js";

declare global {
namespace PixiMixins {
interface Rectangle {
expand(amount: number): this;
}
}
}

Rectangle.prototype.expand = function expand(this: Rectangle, amount: number) {
this.x -= amount;
this.y -= amount;
this.width += amount * 2;
this.height += amount * 2;

return this;
};

pixi.js (>=8.23.0 <9) and @pixi/3d (^0.1.0) are peer dependencies, so your package uses the app's copies instead of shipping its own. Both are dev dependencies too, so the build and the tests have them.

The CLI fills in name from the folder name and author from your git config user.name. Update description in package.json before you publish.

Scripts​

ScriptRunsWhat it does
dev, startxs serveRebuilds on change and serves the project on port 8080, opening examples/
watchxs watchRebuilds on change without a server
buildxs buildCleans, lints, type-checks, then bundles into lib/ and dist/
lintxs lintRuns ESLint on src/ and examples/
formatxs lint --fixRuns ESLint and fixes what it can
typesxs typesType-checks the project with TypeScript
testxs testRuns the Jest tests in src/__tests__/ inside Electron, so they have a real browser environment
docsxs docsWrites API docs from your JSDoc comments into docs/
releasexs releaseBumps the version, tests, builds, deploys docs to GitHub Pages, publishes to npm and pushes tags

xs commands chain with commas, so "test": "xs types,test" runs the type check before the tests.

Build output​

npm run build writes two sets of files:

  • lib/ holds ES module (index.mjs) and CommonJS (index.js) builds plus type declarations. These are what bundlers and Node.js use through main, module, types and exports in package.json.
  • dist/ holds extension.mjs, a single ES module for browsers, set by extensionConfig in package.json. examples/index.html loads it through an import map, with pixi.js and @pixi/3d from jsDelivr.

PixiJS 3D is only published as ES modules, so there's no bundle for a plain <script> tag. "environments": ["node"] in extensionConfig turns that bundle off.

If your extension doesn't use PixiJS 3D, run npm uninstall @pixi/3d, which also removes the peer dependency. Then delete environments and add "bundle": "dist/extension.js" to extensionConfig to build the <script> tag bundle again.

Both folders are generated and listed in .gitignore. The files field in package.json limits the npm package to these two folders, plus package.json, README.md and LICENSE.

Tests on CI​

xs test runs Jest inside Electron with the config in jest.config.mjs. That file is the Extension Scripts default plus a transform for the packages that are only published as ES modules: earcut, which PixiJS uses, and @pixi/3d and its meshoptimizer dependency.

On a Linux CI machine without a display, install xvfb and run the tests through it:

- run: sudo apt-get install xvfb
- run: xvfb-run --auto-servernum npm test

Publishing​

npm run release asks which version to bump to, then runs the tests, builds, deploys the docs and examples to the gh-pages branch, publishes to npm and pushes the git tags. You need to be logged in to npm (npm login) and have a GitHub remote.

The Extension Scripts README lists every command and every extensionConfig option.