Beacon SDK

A package for developing Beacon sheets for the Roll20 app.

Installation

[!WARNING]

In order to develop the Beacon-SDK, it is required to connect the Relay to a local Beacon sheet, usually through npm link.

In Beacon-SDK Repo:

• [ ] npm install
• [ ] npm link
  • Ensure both the Beacon Sheet and Beacon-SDK are using the same Node.js version.
• [ ] npm run watch
  • Enables hot module reloading.

In the local Beacon Sheet

• [ ] Remove the beacon-sdk package name from the sheet's package.json.
  • No need to npm install yet; the next step will handle that.
• [ ] npm link @roll20-official/beacon-sdk
  • This will reinstall the npm packages in the d20 repo, along with your local package.
• [ ] Start up the Beacon Sheet.

In an advanced sheet sandbox game, open up your sheet and if the link was successful, making any changes in Beacon-SDK files should hot reload the Sheet.

System Versioning

In most cases we follow standard semantic versioning.

However when publishing a staging version we append -staging to the end of the version.

Examples:

• Right: ^1.0.17-staging.5
• Wrong: ^1.0.17-staging-5
  • Notice that the last dash is now the one preceding the number 5. This will break usage of the caret when npm tries to fetch this.

Releasing the Package

To release this package using NPM Publish, follow these steps:

[!WARNING] This package is open to the public. Be cautious about what you are publishing to avoid exposing sensitive information or credentials.

1. Update the Version: Update the version number in package.json according to semantic versioning (e.g., 1.0.0 to 1.0.1 for a patch release) and following the guide about staging above&

   npm version <newversion>

2. Publish to NPM: Use the following command to publish the package to NPM. (Make sure you have the necessary permissions to publish the package.)

   PRODUCTION: npm publish

   STAGING: npm run publish-test

3. Push Changes: Push the changes to your repository with the updated package version

   git add package.json
   git commit -m "Release version <newversion>"
   git push origin <branch> (e.g. main or staging)