shelly-scripting

Shelly device scripting

Write device code in TypeScript under src/<solution>/. Each configured entry becomes one ES5 script on a device. The interpreter is not Node or a browser. Support varies by model and firmware. Check that the target supports scripting and the APIs you use.

Rules that prevent crashes

1. Keep callbacks shallow. The official language reference warns that more than two or three levels of nested anonymous functions can crash the device. Define named callbacks before use and register them at startup.
2. Never block. Scripts share the firmware's main task. Use Timer.set and callbacks instead of busy waits or long loops.
3. Track resource use. Each script has at most 5 timers, 5 event handlers, 5 status handlers, 5 in-flight RPC calls, 10 MQTT subscriptions, and 5 HTTP endpoints. Register once, release unused handles, and sequence RPC calls.
4. Keep durable state in KVS or Script.storage. Module variables reset when the script restarts. Validate stored values before using them.
5. Keep the final artifact at or below SCRIPT_MAX_BYTES, 65535 UTF-8 bytes. Script.PutCode rejects 65536 bytes or more. Forge reports size-limit above the limit and size-budget above 80% of it.

Use the device types and checks

The generated device tsconfig loads node_modules/shelly-forge/types/lib.shelly.d.ts and node_modules/shelly-forge/types/shelly.d.ts with noLib: true and types: []. The replacement library rejects missing globals and unsupported array methods. Keep moduleDetection: "force" in both device and test configurations so files without imports or exports stay separate modules. Do not add Node or DOM types to device code to silence errors.

Forge bundles with esbuild's esnext target and uses TypeScript for ES5 lowering. Its __assign and __rest helpers feature-detect missing built-ins and use fallbacks. The final pass normalizes UTF-8 even with --no-minify. AST checks use the unminified ES5 bundle and include code excerpts; size checks use the shipped artifact. For minified builds and check, text locations include (unminified) and JSON findings include bundle: "unminified". build --no-minify writes the matching file. Fix errors and investigate warnings. --strict makes warnings fail the check. Passing these checks does not prove device compatibility.