Principle:MarketSquare Robotframework browser ES2015 Module Transpilation

Overview

The robotframework-browser library's JavaScript extension system requires modules in CommonJS format (using exports and require). However, developers may prefer to write their extension code using modern ES2015+ syntax, which uses import and export statements. This principle describes how Babel is used to convert ES2015+ modules into the CommonJS format that the Browser library can consume.

Core Concept

Modern JavaScript (ES2015 and later) introduced a native module system with export and import keywords. The Browser library's Node.js gRPC server, however, loads extension modules using require(), which is the CommonJS module loading mechanism. These two module systems are incompatible at the syntax level.

Babel is a JavaScript compiler that can transform source code. By using the @babel/plugin-transform-modules-commonjs plugin, developers can write their extensions in ES2015+ syntax and compile them down to CommonJS before passing them to the Browser library.

Why Transpilation Is Needed

The Browser library's extension loading mechanism works as follows:

1. The Node.js gRPC server receives an InitializeExtension request with a file path
2. The server uses require() to load the module
3. The server iterates over the module's exports to discover functions
4. Each function's name, parameters, defaults, and .rfdoc property are extracted

The require() call expects CommonJS semantics. If the file contains export const foo = ... instead of exports.foo = ..., Node.js will throw a syntax error (unless running in ESM mode, which the server does not use).

Transpilation Process

The transpilation follows a simple source-to-output pipeline:

1. Input: ES2015+ source files in a src/ directory
2. Transform: Babel applies the @babel/plugin-transform-modules-commonjs plugin
3. Output: CommonJS-compatible files in a lib/ directory

The transformation:

• Converts export const / export function to exports.name = ...
• Adds Object.defineProperty(exports, "__esModule", { value: true })
• Preserves function signatures, default values, and .rfdoc properties
• Wraps the output in "use strict" mode

What Is Preserved

The transpilation process preserves all the properties that the Browser library needs to introspect:

• Function signatures -- Parameter names and their order remain identical
• Default values -- Default parameter values are carried through unchanged
• The .rfdoc property -- Documentation strings attached to functions survive transpilation
• Function behavior -- The runtime semantics of the function body are unchanged

Limitations

• Dynamic imports (import()) are not relevant since the extension is loaded synchronously via require()
• Top-level await is not supported in CommonJS modules
• The developer must run the transpilation step before passing the module path to the Browser library

Domains

• JavaScript -- The transpilation operates on JavaScript source files
• Build_Tools -- Babel is a build tool in the JavaScript ecosystem

Implemented By

• Implementation:MarketSquare_Robotframework_browser_Babel_Transpile

Related Topics

• MarketSquare_Robotframework_browser_JavaScript_Module_Authoring -- The rules for writing extension modules
• MarketSquare_Robotframework_browser_Babel_Transpile -- Implementation details of the Babel configuration and CLI usage
• MarketSquare_Robotframework_browser_Js_Module_Exports_Pattern -- The target CommonJS pattern that transpilation produces