2.4.1 • Published 10 months ago

@pixi/extension-scripts v2.4.1

Weekly downloads
-
License
MIT
Repository
github
Last release
10 months ago

PixiJS Extension Scripts

Node.js CI npm (scoped)

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

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

CommandDescription
buildAlias for clean,lint,types,bundle
bumpInteractive prompt to bump the version number
bundleBuild dist and lib targets in release mode as well as the types.
cleanRemoves the dist and lib folders
deployAlias for build,docs,upload
docsBuild the src folder into docs folder using webdoc
git-pushDoes git push and git push --tags
lintUsing ESLint to lint the src folder. This supports additional CLI arguments to pass to ESLint, for instance xs lint -- --fix
packLike npm pack but will use clean-package
publishJust like npm publish but invokes clean-package before and after
releaseAlias for bump,test,deploy,publish,git-push
serveRuns watch command plus also opens the examples folder
testRun the unit tests in the test folder. This supports additional CLI arguments to pass to Jest, for instance xs test -- --ci
typesType-check the src folder using TypeScript
uploadUpload files to gh-pages branch
versionOutput the version of @pixi/extension-scripts
watchWatch 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 }}