Packages are sorted into the following three categories:
- Core packages
- Managed APIs
- Third-party packages
Some packages cannot be unselected. These are the packages that are pulled in automatically in response to how you have set up your workspace; however, you can change the version of these packages. Core Packages and Managed APIs default to
latest version, which means that your workspace will always pull in the latest available version. We recommend keeping it that way since we'll be making continuous improvements to event types and Managed APIs, and we want to ensure that your workspace is getting the most up-to-date information regarding third-party services. The only time you might want to take manual control over these package versions is in the event that we decide to release a major version that could potentially introduce some breaking changes. While we will try to avoid such an outcome and will only do it as a last resort, in that situation, you will have the option to downgrade a package to an older version that your workspace was built to work with if you can't immediately upgrade.
When it comes to changes in event types in core packages and Managed APIs that result in breaking changes due to the changes that the third-party service vendor is making, downgrading won't work because the breaking change was introduced by our side as a response to an external change that we have no control over. As a result, you must make manual updates in your workspace to cope with the change.
Third-party packages won't default to the
latest version label, but they will default to the latest concrete version at the time of inclusion. You have to upgrade the package manually by going back to Package Manager and selecting the newer version. ScriptRunner Connect doesn't default to
latest as it does with core packages and Managed APIs because the app has no control over third-party packages and their release schedules, all of which have the potential to include breaking changes. Therefore, staying on a concrete version increases stability.
Managed APIs are automatically pulled in based on the API connections you have declared in your workspace. Most of the time, you don't have to resume manual control over Managed APIs; however, there are cases when you might want to include a Managed API that is not automatically included. The most likely scenario for this would be if you're using a Generic API Connection to connect to a service that we have Managed APIs available for but you are not using our bespoke connector to do so. For example, you may need to use an authentication scheme that ScriptRunner Connect's native connector doesn't support. In this example, you could pull in the Managed API via the Package Manager that wasn't included, construct the Managed API manually, and use it by combining it with the app's Generic API Connection.
No third-party packages are included by default, but you have the ability to pull in any package from NPM.
For example, you may want to include dayjs to work with dates and times more conveniently than the standard library allows. Or maybe you want to add a validator that contains various utility functions for input validation; for example, instead of writing your own regular expression to ensure that an input is a valid email, you could use the
isEmail function from the validator package instead.
Importing third-party packages
Use ES(6) Modules syntax when importing packages into ScriptRunner Connect instead of CommonJS, which makes use of the
Returning to the example of the validator package, the correct import statement would be:
import validator from 'validator';
Or, if you would like to import a single function from the validator:
import isEmail from 'validator/lib/isEmail';
Dealing with types
Today, most NPM packages either come with TypeScript types natively or have community-written types available from DefinitelyTyped project. However, some packages may have neither. The ScriptRunner Connect editor uses TypeScript types to power IntelliSense, which is extremely useful, so getting types sorted out is important.
Packages with native support
NPM packages with native support have a TS logo next to the title on the NPM page (dayjs for example). Simply include the package, and ScriptRunner Connect automatically picks up the types.
Packages with community support
Packages with community support have the DT (DefinitelyTyped) logo next to the title on the NPM page. This means you should also include the DefinitelyTyped package alongside the main package you're trying to include.
Potential sync issues
Be aware that DT types have the potential to become out of sync with the package that they aim to add types of support for. For example, a package author may decide to convert their package from DefinitelyTyped to TypeScript. In this case, case NPM should reflect the correct information, displaying the TS icon instead of DT.
Packages without any support
If a package has no support, you can still attempt to use it, but you won't receive any IntelliSense support, and the editor and compiler will complain. However, you should be able to use it if you have the ability to use the package blindly (without any editor support).
Your mileage may vary
There are two reasons that some NPM packages can't be used with ScriptRunner Connect:
- Incompatibility with the ScriptRunner Connect runtime
For example, if the package was exclusively built to work on Node, it most likely won't be compatible because we're not implementing Node APIs. ScriptRunner Connect runtime aims to implement APIs that are standardized—APIs that exist in browsers and in more modern server-side/cloud runtimes that aim to take advantage of WinterCG initiative, which we are also aiming to achieve.
- Package structure issues
We plan to solve this issue, so if you stumble upon a package that should work but fails, let us know so we can investigate. Also, packages that fail due to lacking types or type-loading failures can still be used, but it takes a little more work to get them sorted out.
To make it easier to include third-party NPM packages, ScriptRunner Connect curates a list of verified packages that are confirmed to work well in ScriptRunner Connect. This list of verified packages will grow over time.
If you can't find the package that solves your problem in the verified list, you can try to add any unverified NPM package, but, as mentioned, your mileage may vary. The easiest approach is to include the package and see if it works; if it doesn't, you can look for alternatives.
Package management can be quite a challenge, even for seasoned developers. We welcome your feedback about packages you want to use, so contact us in our Slack community channel or send feedback via the in-app form with an explanation of the problem you're trying to solve, and we'll be happy to look for SR Connect friendly packages that help solve your business problem.