Reactor Extensions Spec

The EVRYTHNG Reactor is a powerful programmatic feature allowing projects to contain JavaScript scripts that react to events in the Platform, such as property updates or created actions. This part of implementing an EVRYTHNG integration is usually completely up to the developer to design and write themselves, and provides the most flexibility.

However, in some cases, there may be modular parts of a project that can be generalised and easily re-used in another project, or even by another developer. We call these Reactor Extensions, and there are numerous advantages to creating and sharing them:

  • Enable sharing of reusable Reactor scripts by following a common specification.
  • Allow the quick creation of more modular projects in the EVRYTHNG Platform.
  • Benefit from the shared work of other developers in the ecosystem.
  • Easily add existing Reactor Extensions to a project to get add modular features with minimal effort and configuration.

With this possibility in mind, the following specification for Reactor Extensions is described, and serves as a guideline to be used when there is potential for a useful Reactor script to be re-used and shared to speed up development.


Specification

 A 'Reactor Extension' script MUST

  • Reside inside a public GitHub repository.
  • Contain in the root directory:
    • package.json - npm-compatible JSON file containing at least evrythng-extended in dependencies.
    • main.js - source file including at least one Reactor event handler.
  • Require no further code changes to deploy except:
    • Setting of preferences/configuration values as constants at the top of main.js.
    • Setting of secret credentials or third-party API keys as constants at the top of main.js.

 A 'Reactor Extension' script SHOULD

  • Take advantage of built-in EVRYTHNG Platform features, such as action or Thng customFields to deliver parameters and other data to the script at runtime.
  • To stay within your account usage limits, use Reactor filters as much as is reasonably practicable to minimise the impact.
  • Use the recommended single Promise chain pattern to guarantee that done() is called, and all errors are caught, and also to ensure logs are not lost and retries (which could produce side-effects) are avoided.
  • Include further dependencies required either:
    • In package.json - if they are npm modules.
    • In local subdirectories to adjacent main.js - if they are local files or libraries.

Note: if more than one source file aside from main.js exists, the ‘bundle upload’ method must be used to deploy it.

A ‘Reactor Extension’ script MUST NOT

  • Require custom code changes beyond previously discussed config/secret constant values.
  • Cause itself run or be invoked indefinitely, or break any of the other limits on Reactor scripts.

Examples

See the Reactor Scripts page for a list of example Reactor scripts that meet and implement this specification, and so can be classed as Reactor Extensions.

Updated about a year ago


Reactor Extensions Spec


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.