ESMification Prep: What is JSM?

[Tooru Fujisawa]

Hi, everyone.

ESMification is a project to switch the Mozilla-specific JSMs in privileged code to the standard ECMAScript modules (ESM). To get everyone ready and on the same page, we have written a series of three emails to help contextualize the transition.

The migration is going to be done by each team, and today I’d like to provide the background of Firefox’s current module system, to help everyone get familiar with it and ready for the migration.

What is JSM?

A JSM is a Mozilla-specific JavaScript module used in the Firefox codebase.  It’s a plain JavaScript file with `.jsm` file extension, and an `EXPORTED_SYMBOLS` global variable that defines the list of exported global variables.

Variables exported by the module can be imported from other JS files, with `ChromeUtils.import` API and friends.

A JSM is a per-process singleton, shared among all consumers in the process. The JSM file is evaluated when it’s loaded at the first time, and subsequent loads for the module returns the cached module.

All JSM files are loaded into a dedicated shared global.

How does a JSM look like?

A JSM is a plain JavaScript file with `EXPORTED_SYMBOLS` global variable, so the minimal JSM file is something like the following:

const EXPORTED_SYMBOLS = [”SayHello”];

function SayHello() {

  console.log(”Hello, World!”);

}

`EXPORTED_SYMBOLS` is an array that contains the list of strings, with the name of global variables exported from this module.

JSM files are usually accessed by `resource://` URI or `chrome://` URI.

JSM files accessed by `resource://` URI are defined with the `EXTRA_JS_MODULES` variable in the `moz.build` file.

EXTRA_JS_MODULES += [

  "Hello.jsm",

]

How are JSMs used?

Variables exported by JSMs can be imported with `ChromeUtils.import` API.

const { SayHello } = ChromeUtils.import(

  "resource://gre/modules/Hello.jsm"

);

SayHello();

If the module is not immediately used, it can be loaded with a “lazy getter”, and the module is loaded when the property is accessed at the first time.

const lazy = {};

XPCOMUtils.defineLazyModuleGetter(lazy, {

  SayHello: "resource://gre/modules/Hello.jsm"

});

...

lazy.SayHello();

What will happen to JSMs during ESMification?

JSMs like this are going to be replaced with equivalent ESMs (ECMAScript modules) in the ESMification project.

Stay tuned for the next preparation series that will explain the ECMAScript modules!

Status Update

Renamed New API

The new APIs are renamed in order to make it clearer they’re about modules.

• Basic import API: `ChromeUtils.importESModule`
• Defining lazy getter: `ChromeUtils.defineESModuleGetters`
• Registering window/process actors: `esModuleURI` property for each existing API
• Static component registration: `esModule` property in components.conf
• Querying loaded modules: `Cu.isESModuleLoaded` and `Cu.loadedESModules`

New ESMification Matrix room

If you have questions regarding the ESMification, feel free to ask in the #esmification matrix room!