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+.
- 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
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"
}
}
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 |
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"
}
}
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 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 forbundle
(default:named
)bundleSource
string - Input for thebundle
, fallback tosource
(default:null
)bundleModule
string - The relative path to the output browser module (.mjs
) file.bundleModuleSource
string - Input for thebundleModule
, fallback tosource
(default:null
)bundleModuleExports
string - Output exports forbundleModule
(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
).docsCopyright
string - Copyright in the docs (defaults: package.json'sauthor
)docsDescription
string - HTML meta description in docs (defaults: package.json'sdescription
)docsDestination
string - Relative path to the output documentation folder (default:docs
)docsGoogleAnalytics
string - OptionalUA-*
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'skeywords
)docsName
string - Application name in docs (defaults: package.json'sname
)docsRepository
string - URL for repository (defaults: package.json'srepository.url
)docsTitle
string - HTML base title in docs (defaults: package.json'sname
)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']
)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
)
{
"extensionConfig": {
"namespace": "PIXI.myextension",
"bundle": "dist/pixi-my-extension.js",
"bundleModule": "dist/pixi-my-extension.mjs",
"globals": {
"lodash": "_"
}
}
}
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
uses: GabrielBB/xvfb-action@v1
with:
run: npm test