Optional Transpilation

The Flow Engine must transpile javascript to fully support ES6 module syntax. However, transpilation comes at a significant performance cost.

This document describes:

• How to enable transpilation if required
• How to write performant flows without transpilation

Note

Agent versions 1.7.16 or lower will always transpile. Versions 1.7.17 only transpile when enabled.

Performance Trade offs

With transpilation enabled, flow javascript can have statements like import {x} from "XYZ"; or export var a = "A";.

There are two key performance benefits from not transpiling:

• The start time for flows typically drop by 50%
• The RAM requirements of running a flow drops by roughly 800MB

Enabling Optional Transpilation

If transpilation is needed for a flow, update the flow manifest.json file as follows:

1. Under the "resources" list, for each item with "provider": "js" add the following to "options": "options": [{"babelPlugins": [["transform-modules-commonjs", {"strictMode": false}]]}]
2. Your manifest.json should now look like:

{
  "main": [
    "main"
  ],
  "resources": [
    // ...
    {
      "path": "main.js",
      "provider": "js",
      "runtime": "",
      "options": [
        {"babelPlugins": [["transform-modules-commonjs", {"strictMode": false}]]}
      ]
    },
    {
      "path": "std-nodes.js",
      "provider": "js",
      "runtime": "",
      "options": [
        {"babelPlugins": [["transform-modules-commonjs", {"strictMode": false}]]}
      ]
    },
    {
      "path": "std-nodes.json",
      "provider": "visualscript",
      "runtime": "",
      "options": []
    },
    // ...
  ]
}

3. Transpilation is now enabled, and you should be able to run this flow on any agent version which supports the Flow Engine.

Backwards Compatability

For flows requiring transpilation it is always safe to include the option {"babelPlugins": [["transform-modules-commonjs", {"strictMode": false}]]}. This option has no effect on older versions of the agent.

Flows without Transpilation

When creating new flows, any custom libraries which make use of module syntax like import {x} from "XYZ"; or export var a = "A" must be converted to ES5 compatible syntax.

1. Replace import with require:

   import {x, y, z} from "XYZ";
   becomes:

   var x = require("XYZ").x;
   var y = require("XYZ").y;
   var z = require("XYZ").z;
2. Replace export with the exports object:

   export a = "A";
   export b = "B";
   export c = "C";
   becomes:

   var a = "A";
   var b = "B";
   var c = "C";
   exports.a = a;
   exports.b = b;
   exports.c = c;

Troubleshooting

"failed to create flow instance"

I see "failed to create flow instance" when running my flow

Search through the error messages. If you see “failed to load resources… Unexpected reserved word”; then the fix is to enable transpilation for that flow. Follow the guide above for Enabling Optional Transpilation.