pixijs / extension-scripts

Build-time scripts for setting up extensions

PixiJS Extension Scripts

Contains all the tools common for building extensions for PixiJS. While this tool is rather generic and can be used for variety of purposes, it has convenient defaults that are specifically designed for PixiJS v7+.

Features

• Consistent linting style with ESLint
• Builds using Rollup and ESBuild
• Testing using Jest (with Electron runner)
• Documentation building with webdoc
• Deployment using gh-pages on GitHub
• Tidy package.json with clean-package while publishing.
• Publishing release workflow

Getting Started

Simply add these things to your package.json. All scripts (a.k.a., commands) are optional. This structure (main, types, module, exports) provides the best backward-compatibility with Node's new module exports.

{
  "main": "lib/index.js",
  "module": "lib/index.mjs",
  "types": "lib/index.d.ts",
  "exports": {
    ".": {
      "import": "./lib/index.mjs",
      "require": "./lib/index.js",
      "types": "./lib/index.d.ts"
    }
  },
  "scripts": {
    "build": "xs build",
    "docs": "xs docs",
    "release": "xs release",
    "start": "xs serve",
    "test": "xs test",
    "watch": "xs watch"
  },
  "devDependencies": {
    "@pixi/extension-scripts": "latest"
  }
}

Commands

Command	Description
build	Alias for clean,lint,types,bundle
bump	Interactive prompt to bump the version number
bundle	Build dist and lib targets in release mode as well as the types.
clean	Removes the dist and lib folders
deploy	Alias for build,docs,upload
docs	Build the src folder into docs folder using webdoc
git-push	Does git push and git push --tags
lint	Using ESLint to lint the src folder. This supports additional CLI arguments to pass to ESLint, for instance xs lint -- --fix
pack	Like npm pack but will use clean-package
publish	Just like npm publish but invokes clean-package before and after
release	Alias for bump,test,deploy,publish,git-push
serve	Runs watch command plus also opens the examples folder
test	Run the unit tests in the test folder. This supports additional CLI arguments to pass to Jest, for instance xs test -- --ci
types	Type-check the src folder using TypeScript
upload	Upload files to gh-pages branch
version	Output the version of @pixi/extension-scripts
watch	Watch the code in development mode, updates on changes

Chaining

Commands can also be chained together easily separated by a comma. For example, the following will serially call test, build, then finally docs. This can be used as a convenient alternative for pre* and post* package.json scripts.

{
  "scripts": {
    "test": "xs test,build,docs"
  }
}

Project Structure

Generally, the project structure is baked-in to the defaults, however, most of this can be customized (see the Configuration section below).

• ./dist - Generated folder for the ES2017 browser bundles
• ./docs - Generated folder for the API documentation
• ./examples - Contains any examples or demos use to test the project
• ./lib - Generated folder for ES2020 modules and types
• ./src - Contains all the source code (TypeScript files)
• ./test - The Jest unit-tests

Configuration

Configuration can be provided using the extensionConfig field in package.json:

• bundle string - The relative path to the output browser file (.js).
• bundleExports string - Output exports for bundle (default: named)
• bundleSource string - Input for the bundle, fallback to source (default: null)
• bundleModule string - The relative path to the output browser module (.mjs) file.
• bundleModuleSource string - Input for the bundleModule, fallback to source (default: null)
• bundleModuleExports string - Output exports for bundleModule (default: named)
• clean string[] - List of files to clean before each build.
• deployFiles string[] - Glob pattern for files to deploy (default: {dist,examples,docs}/**).
• deployBranch string[] - Branch where to do the deployment (default: gh-pages).
• deployRoot string - Root folder to do deploy, used in combo with deployFiles (default: .).
• docsCopyright string - Copyright in the docs (defaults: package.json's author)
• docsDescription string - HTML meta description in docs (defaults: package.json's description)
• docsDestination string - Relative path to the output documentation folder (default: docs)
• docsGoogleAnalytics string - Optional UA-* identifier for reporting to Google Analytics.
• docsIndex string - Relative path to markdown file to use as the index page for documentation (default: README.md)
• docsKeywords string - HTML meta keywords in docs (defaults: package.json's keywords)
• docsName string - Application name in docs (defaults: package.json's name)
• docsRepository string - URL for repository (defaults: package.json's repository.url)
• docsTitle string - HTML base title in docs (defaults: package.json's name)
• environments string[] - Environments supports for output, only values supprted node, browser (default: ['node', 'browser'])
• globals object - Output globals as defined by Rollup. This is used for creating the browser bundle. All defaults are provide for the core package of PixiJS (e.g., @pixi/core, @pixi/sprite, etc).
• jestConfig string - Optional path to the Jest config file (default: null)
• lint string[] - List of additional folders or files to lint. (default: ['src', 'test', 'examples'])
• moduleSource string - Input for the module output, fallback to source. Supports globs. (default: null)
• namespace string - User-defined global namespace for the bundle.
• serve string - Relative path to the serve folder (default: examples).
• silent boolean - Whether to silence the output (default: false)
• source string - The entry-point for building the extension (default: src/index.ts)
• tsconfig string - Relative path to the tsconfig file for doing type check (default: tsconfig.json)

Example

{
  "extensionConfig": {
    "namespace": "PIXI.myextension",
    "bundle": "dist/pixi-my-extension.js",
    "bundleModule": "dist/pixi-my-extension.mjs",
    "globals": {
        "lodash": "_"
    }
  }
}

Environment Variables

• XS_PUBLISH_TAG string - The npm --tag value to use when running the publish command (default: latest)

GitHub Actions

If you're going to run xs test on GitHub Actions, please keep in mind that it requires xvfb since the tests are run within Electron. You can add the following to your workflow scripts to run it:

Before

- name: Test
  run: npm test

After

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

Publishing on GitHub Actions

Publishing on GitHub Actions requires a little customization. Typically, running xs release locally will also publish, however, if you want to defer publishing on GitHub Actions, you can modify the default xs release in your package.json like this:

{
  "scripts": {
    "build": "xs build",
    "release": "xs bump,test,deploy,git-push",
    "publish-ci": "xs publish",
  }
}

Here's a snippet of the a GitHub Actions workflow to trigger a publish when a release is published. For more information on creating publishing workflow check out this documentation.

name: Publish Package
on:
  release:
    types: [published]
jobs:
  publish:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '20.x'
        registry-url: 'https://registry.npmjs.org'
    - run: npm ci
    - run: npm run build
    - run: npm run publish-ci
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Finally, if you need to publishing to a different dist-tag when publishing, you can use the XS_PUBLISH_TAG environment variable. In this example, prereleases will be published to a beta dist-tag.

name: Publish Package
on:
  release:
    types: [published]
jobs:
  publish:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '20.x'
        registry-url: 'https://registry.npmjs.org'
    - run: npm ci
    - run: npm run build
    - run: npm run publish-ci
      if: github.event.release.prerelease
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        XS_PUBLISH_TAG: beta
    - run: npm run publish-ci
      if: github.event.release.prerelease == false
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}