JavaScript

A JavaScript transformer gives you a small script to work with your data: parse structures, apply logic, build new values, and pass extra data along the chain with ctx.

You'll find JavaScript in the same places as Lua:

In any of those chains, tap a row to edit it, drag the handle to reorder, and swipe right to left to delete a transformer or action.

Your script's return value becomes the value the next transformer or action receives.

Lists start at 0. Lua lists start at 1 — do not copy Lua index samples.

Scripts run in strict mode. A bare x = 1 (no let, const, or var) throws. Declare every name.

There is no console. console.log(...) throws. Use return to send a value down the chain.


Quick reference

Goal Idea
Where it runs Data transformers pipe on a data source, data piece, or component. Tap actions pipe when you tap a data piece or component. Periodic action pipes on a data piece, a group, a Freeform section, a custom screen, or a bottom sheet.
Read data / fields Globals value, value.field, value["key"], value[0] (lists start at 0)
Nested field value?.region?.name
Connection error in transformers ctx.error.message, ctx.error.kind, sometimes ctx.error.statusCode; set ctx.error = null to mark it handled.
MQTT details ctx.transport.topic, ctx.transport.receivedAt, … when ctx.transport is present.
HTTP ctx.transport.responseTime, ctx.transport.statusCode, ctx.transport.url, ctx.transport.requestHeaders, ctx.transport.responseHeaders, …
WebSocket ctx.transport.event, ctx.transport.mode, …
Timer tick ctx.transport.reason, ctx.transport.intervalMs, ctx.transport.receivedAt.
Objects ↔ JSON text JSON.stringify(x), JSON.parse(str).
Binary ↔ base64 text base64Encode(x), base64Decode(str).
Read another data source sourceValue("Name"), sourceRaw("Name").
ENV variable env.my_key. See ENV variables.
Format a timestamp new Date(), toISOString(). Text length: value.length.
Return a result return the new value for the next transformer or action.

See also Lua, JSONPath, Expressions, Expressions in editors, and Periodic action pipes.


Where it runs

Data transformers pipe runs on a data source (MQTT, WebSocket, Timer), a data piece, or a component. HTTP sources and destinations use the Actions / Transformers pipe instead — JavaScript there sees the same names as a source transformer (value, raw, ctx, env). Tap actions pipe runs on a data piece or component when you tap it. If the data piece has tap actions turned on, the tap does not reach components.

Which globals your script can see depends on where it runs.


Globals: transformer vs tap action

Data transformer (source, data piece, or component)

Tap action

Summary (live vs fixed):

Name In a data transformer In a tap action
value Live, changes after each transformer Live, changes after each action
raw Fixed: value at the start of the chain (or the Actions / Transformers pipe) Fixed: data right after the source's transformers (or the Actions / Transformers pipe)
transformed Not available Fixed: what the data piece showed when you tapped it
ctx Live, including the connection error state Always an object
env App-wide text (env.my_key) Same
comp This component (runtime look only). On a data piece script: comp.bgColorId. Same
components Other components on this data piece, by ID (runtime look only) Same

What a script returns

Example (transformer — extract and convert a temperature):

if (value && value.temp != null) {
  return value.temp * 1.8 + 32;
}
return value;

Example (tap action — remember the tap time):

ctx.lastTap = new Date().toISOString();
return value;

Passing extra data with ctx

value is the main data. Later transformers or actions often replace it. Put anything you still need on ctx.

In a transformer chain, later transformers in that same chain see the write:

ctx.unit = value.unit;
return value.temperature;

The next JavaScript, Lua, expression (ctx.unit), or JSONPath ($.ctx.unit) can read it. Extra keys you set on a source transformer do not copy to component transformers.

In a tap chain, the same bag is shared across actions. Don't overwrite error or transport. Set ctx.stopPipeline = true to skip every remaining transformer or action in this run. Stop pipeline does the same without a script.

See Tap actions and Data transformers.


Change how a component looks

On a data piece or component transformer or tap action (not on a data source or HTTP list), JavaScript can change how components look until the next run. The change is not saved.

comp.visible = false;
comp.textColorId = "error";
components.label1.value = "Overheating";
return value;

Objects, arrays, and JSON

Objects and lists arrive as JavaScript objects and arrays. The first list item is value[0], not value[1].

This comes from the transformer's pass structured value setting, which is on by default. The editor has no switch for it; it is only in the saved configuration. When it is off, objects and lists arrive as JSON text instead — use JSON.parse(value) to turn them back into an object. Text, numbers, true/false, and binary arrive the same either way.

return { indoor: value.temp, n: value.items[0] };

Unlike Lua's json_encode / json_decode, there is no second error return — wrap in try / catch if you need to recover.


Binary data

File and image values are a Uint8Array. value.length is the byte length.

JSON.stringify cannot encode binary — use base64Encode first.

Keep large files and images out of JavaScript when you can. Crossing into the script copies every byte as a number, which is slow on a big image.

base64Encode(x) turns binary (or text) into base64 text. base64Decode(str) turns base64 text back into a Uint8Array. On failure they throw.


Other data sources

const outdoor = sourceValue("Weather");
if (outdoor == null) return value;
return { indoor: value.temp, outdoor: outdoor.temp };

An unknown or empty name throws. During a source transformer on source X, sourceValue("X") still returns the previous stored value until that chain finishes.


JavaScript vs Lua vs JSONPath vs expressions

A comparison table is in Expressions in editors.


Handling connection errors

When a connection fails, ctx.error is an object with message, kind, and statusCode (when one is available). After success, ctx.error is null.

ctx.error = null;
return value;

Later transformers in the chain see the cleared state. Clearing ctx.error in a component transformer only affects that component.

To turn a connection error into a hard stop:

throw new Error(ctx.error.message);

MQTT / HTTP / WebSocket / Timer: ctx.transport

The fields match Lua: MQTT topic, qos, retain, receivedAt; HTTP method, url, responseTime, statusCode, requestHeaders, responseHeaders; WebSocket mode, event, url; Timer reason, intervalMs.

return ctx.transport.responseTime || 0;

Strings, regular expressions, and time

Text length is value.length. Remainder is %. Regular expressions are native (/\d+/, "\\d{4}" in a quoted string).

new Date().toISOString() is the current time in UTC.


Sandboxing

JavaScript here can't load modules, read files, use a shell, or send HTTP, MQTT, or WebSocket. To send from a tap, use HTTP request, MQTT send, WebSocket send, or Trigger data destination — see Tap actions.

A script that runs longer than 2 seconds is stopped. The dashboard freezes for those 2 seconds, then the script errors. It does not run in the background.

JSON.parse, JSON.stringify, Math, Date, and the helpers above are available.