Testing and Publishing Changes to openspace-api-js

This guide explains how to test local changes to openspace-api-js in a consuming repository, such as the WebGui. It also explains how to publish those changes as prereleases or stable releases using npm.

These steps apply to any package change, including newly generated types, new Topics, updated Lua library functions, and bug fixes.

1. Test local changes in a consuming repository

  1. In the openspace-api-js repository, run npm pack. This creates a tarball, e.g., openspace-api-js-x.x.x.tgz.

  2. In the consuming repository, run npm install <path-to-openspace-api-js-x.x.x.tgz> to install it as a local dependency pointing at your build.

2. Publish a prerelease package for testing

  1. Bump to a prerelease version:

    • For a new prerelease, set an explicit version:

      npm version x.x.x-dev.0 --no-git-tag-version

      --no-git-tag-version avoids immediately committing the version bump.

    • To iterate on an existing prerelease (e.g., new Lua definitions, a new Topic), bump the prerelease number instead of jumping to a new patch/minor/major version:

      npm version prerelease --preid=dev --no-git-tag-version

      This bumps, for example, 1.0.3-dev.0 to 1.0.3-dev.1.

  2. Publish under the dev tag:

    npm publish --tag dev

    This ensures the prerelease is not installed by a plain npm install openspace-api-js.

  3. Consumers can install it with npm install openspace-api-js@dev, or a specific version with npm install openspace-api-js@1.0.3-dev.0.

3. Upgrade from a prerelease to a stable release

When ready to promote a prerelease to a stable release, run:

npm version 1.0.3 --no-git-tag-version
npm publish

If you instead want to change which already-published stable version installs by default (without publishing again), repoint the latest dist-tag to that stable version, for example:

npm dist-tag add openspace-api-js@1.0.3 latest

Note that this only changes what npm install openspace-api-js resolves to. It does not turn a prerelease into a stable release.

Note

Versioning: version numbers follow semantic versioning, major.minor.patch (e.g., 1.0.3). Use npm version patch, npm version minor, or npm version major for stable releases depending on the scope of the change. This bumps the corresponding version number by 1. For -dev builds, use the prerelease commands above.

Again use --no-git-tag-version to avoid automatically committing the change.