Script Libraries

Last updated

A library is shared code that every script can call. Put parsing routines, unit conversions and constants in a library once, instead of copying them into ten scripts.

Open it with Libraries in the sidebar, or the Libraries button on the Scripts page. The page is titled Script Libraries.

Creating a library

1. Click New Library.
2. Type a name in Library name (e.g. utils, helpers)... and click Create.
3. Select the library in the list and write its code. Export what scripts should use by assigning to exports.
4. Click Save (Ctrl+S).
5. In any script, call it by the library's name: utils.celsiusToF(25).

// Library "utils"
const clampValue = (v, min, max) => Math.min(Math.max(v, min), max);

exports.clamp = clampValue;
exports.celsiusToF = (c) => c * 9 / 5 + 32;
exports.LINE_NAMES = { 1: 'Press Line', 2: 'Weld Line' };

// Any script
const pct = utils.clamp(Number(tags.read('Mixer-1', 'load')), 0, 100);
log(utils.LINE_NAMES[2], utils.celsiusToF(21));

Name rules

Rule	Detail
Characters	Must be a valid JavaScript identifier: start with a letter, _ or $, then letters, digits, _ or $. No spaces or hyphens. Error: Library name must be a valid identifier (letters, numbers, underscores).
Unique	Case-insensitive. Error: A library with this name already exists.
Avoid API names	Names such as tags, db, http, log are blocked outright: "tags" is a built-in script API and can't be used as a library name.
Avoid script variable names	A script with const utils = … at the top level fails once a library named utils exists.

How libraries are loaded

• Every saved library is inserted in front of every script run, sorted by name, as const name = (function () { const exports = {}; …your code… return exports; })();.
• Only exports.x = … works. module.exports = … fails with ReferenceError: module is not defined, and export / require are not supported. That failure is caught per library, so it leaves just that one library empty rather than failing every script — a script that actually calls into it gets … is not a function.
• Top-level code in a library runs at the start of every script run, so keep it to definitions. Don't do HTTP calls or heavy work at load time.
• A library can call another library inside its functions. Calling another library while loading only works if that library's name sorts earlier.
• Libraries have the same sandbox as scripts: tags, db, http and the rest are available inside library functions.
• Changes take effect on each script's next run; nothing needs restarting.

Note: A library with a syntax error is skipped — it loads as an empty object rather than a full library, so only scripts that actually call into it fail (with … is not a function), not every script on the appliance. Use Run Test before saving to catch the mistake directly.

Testing a library

The Test panel runs the library code as it is in the editor, including unsaved changes, in the script sandbox, together with your other saved libraries.

1. In the snippet box, call your library and return a value, e.g. return utils.clamp(150, 0, 100);. Leave it empty to list the library's exports.
2. Click Run Test.
3. The result shows ✓ Completed or ✗ Failed, any log lines, the error, and under Returned the returned value (objects are shown as JSON).

The test runs as the logged-in user, so users.* works only if you are an administrator. It can have side effects: a test that writes tags or inserts rows really does so. It stops after 15 seconds of continuous execution.

The test always uses the library's saved name. If you renamed it without saving, refer to the old name in the snippet.

Permissions

Action	Roles
View libraries	Anyone with page access to Libraries
Create, edit, rename, Run Test	admin, editor
Delete (trash icon)	admin; asks Delete library? first. Editors don't see the icon.

API endpoints

Method	Path	Purpose
GET	/api/script-libraries	List libraries
POST	/api/script-libraries	Create (admin, editor)
PUT	/api/script-libraries/:id	Update name/code (admin, editor)
DELETE	/api/script-libraries/:id	Delete (admin)
POST	/api/script-libraries/:id/test	Run unsaved code with a test snippet; body { "code", "testCode" } (admin, editor)

See also

• Scripts
• Script Sandbox, Limits & Errors
• Scripting API Reference
• Script Examples