This project consists of multiple NPM packages, managed in one repository with Lerna. All code, excluding Node.js-based tests, is written in TypeScript. I recommend using VSCode for linting and type information, which becomes especially helpful when dealing with glTF schema objects.
After cloning the repository, run:
NOTICE: If installation fails with errors during
node-canvascompilation, you may need need to complete the one-time setup described in https://github.com/Automattic/node-canvas#compiling.
The project relies on Yarn workspaces and will not build with npm. To build and test all code, run:
yarn run dist yarn test
To run an arbitrary command across all packages:
lerna exec -- <command>
While working, use
yarn run watch to watch and rebuild code after changes. To use a local
version of the CLI, run
yarn link within the
packages/cli directory. Then
gltf-transform -h will use local code instead of any global installation.
Before adding new features or packages to the repository, please open an issue on GitHub to discuss your proposal. Some features may not fit the current scope of the project, or may be more than I am able to maintain long-term. Even if a feature does not end up in this repository, custom extensions and functions can be defined and used externally. Changes including test coverage are strongly preferred.
New features should be compatible with both Node.js and Web, though exceptions may be possible in certain situations. To accomplish that, any platform-specific resources (like instances of HTMLCanvasElement or headless-gl) are passed into API functions by the user, rather than being created by the API directly.
I recommend compiling with Node.js v12.x, which is the latest version with a prebuilt binary for
gl as of April 2020.
Runtime dependencies should be installed only to the sub-package in which they are needed. Any
devDependencies are shared across all packages, and should be installed in the project root. Pull
requests should omit any changes to
Documentation and examples are written in JSDoc comments on the relevant classes and methods, processed with TypeDoc, and rendered to a custom TypeDoc theme. Additions and clarification are welcome, and examples may be added inline alongside class documentation. Certain JSDoc tags have notable meanings within this project:
@internalmethods and classes are (1) hidden from documentation, and (2) not included in TypeScript definitions for the package. This code is intended only for use within the defining package.
@hiddenmethods and classes are hidden from documentation, but still included in TypeScript definitions for the package. This code is not intended for wide use, but may be necessary for other packages in the glTF-Transform monorepo.
glTF-Transform supports the complete glTF 2.0 core format, and some extensions. Most official Khronos Group extensions (those prefixed with
KHR_) will be implemented on a rolling basis — pull requests are very welcome. Multi-vendor extensions (prefixed with
EXT_) may be included on a case-by-case basis. Single-vendor extensions (any other prefix) are unlikely to be included directly in the project, although glTF-Transform does provide APIs to build and maintain implementations for those extensions externally.
Suggestions and PRs for new Functions are also generally welcome.
NOTE: Only the maintainer can create new releases.
All packages are published together. To create a standard release:
lerna publish [ patch | minor | major ] --force-publish "*" --otp <OTP>
To create an alpha release:
lerna publish prerelease --dist-tag alpha --force-publish "*" --otp <OTP>
If a release contains a new package,
-- --access public must be appended. Lerna has historically
been finicky with 2FA OTPs.