scripts/README.md
This directory contains the build and test orchestration for PixiJS.
| Command | Description |
|---|---|
npm run build | Full production build (bundle + types + DTS bundle) |
npm run build:lib | Dev build (bundle + types, no DTS bundling) |
npm run build:docs | Generate TypeDoc API documentation |
npm start | Start playground dev server + watch mode |
npm test | Run all checks (lint, types, index, prune, unit, visual) |
npm run test:unit | Unit tests only |
npm run test:visual | Visual regression tests only |
npm run test:lint | Lint checks only |
npm run test:types | Type checking only |
npm run lint | Lint with auto-fix |
build.mts)The build script accepts two flags:
--lib — Library-only build. Skips package exports validation and DTS bundle generation. Sets LIB_ONLY=1 for Rollup so only the library bundle is emitted.--dev — Development mode. Allows type-check errors without failing, and skips dts-bundle-generator.index.ts files and validates package exports. The exports step is skipped for --lib without --dev.tsc, copying .d.ts files, fixing types, and optionally generating the DTS bundle.watch:lib — Rebuilds on source changes with --lib --dev. Writes .build-status.json via build-status.mjs so the playground can show a compiling/ready indicator.watch:build — Full dev rebuild on source changes (includes types).watch:docs — Rebuilds TypeDoc docs on source or markdown changes.test.mts)The test script runs checks in two phases. Pass selectors to run specific checks:
npm run test [selector...] [-- flags]
| Selector | Phase | Blocking | Description |
|---|---|---|---|
lint | Static | Yes | ESLint with --max-warnings 0 |
types | Static | Yes | tsc --noEmit against build, examples, and playground configs |
index | Static | Yes | Validates barrel index files are up to date |
prune | Static | No | Knip dead-code analysis (failure is reported but non-blocking) |
unit | Jest | Yes | Unit tests (excludes tests/visual/) |
visual | Jest | Yes | Visual regression tests (tests/visual/) |
debug | — | — | Modifier: runs Jest in headful mode with DEBUG_MODE=1 |
When no selectors are specified, all checks run.
lint, types, index, and prune run in parallel. If any blocking check fails, Jest tests are skipped and the process exits with code 1.unit and visual run sequentially. The debug selector enables headful browser DevTools for interactive debugging.Extra CLI flags (those starting with -) are forwarded to the underlying tool.
build-status.mjs)A small helper used by watch:lib to signal the playground's build status indicator:
node scripts/build-status.mjs start # writes { status: 'compiling', startedAt: ... }
node scripts/build-status.mjs done # writes { status: 'ready', completedAt: ... }
The status is written to .build-status.json in the project root (git-ignored). The playground's useBuildStatus hook polls this file to show a yellow (compiling) or green (ready) indicator.