Browser Window Scripts
Each browser window runs its front-end scripts in its own global object. This page explains how those scripts load and how to turn one into a module.
How the Scripts Load
browser.xhtml loads two
scripts with <script> tags:
global-scripts.js and
browser-main.js. Other
top-level windows load global-scripts.js too, so put a script that only the
browser window needs in browser-main.js.
The rest of the window’s scripts load in one of three ways. New code should only be added as modules.
Subscripts
Most scripts load into the window’s global object with a loadSubScript call:
Services.scriptloader.loadSubScript("chrome://browser/content/browser-init.js", this);
global-scripts.js and browser-main.js contain a series of these calls.
Modules
A module loads with ChromeUtils.importESModule instead:
ChromeUtils.importESModule("chrome://browser/content/tabbrowser/tabgroup.mjs", { global: "current" });
The { global: "current" } option loads the module into the window’s global
object (see JS Loader APIs). Each window then
gets its own copy of the module, and the module can read the window’s globals
by name.
Lazily Loaded Modules
A module that defines a global for other scripts loads lazily. browser.js defines a getter for the global, which imports the module the first time a script reads it:
ChromeUtils.defineESModuleGetters(
this,
{
StatusPanel: "chrome://browser/content/tabbrowser/status-panel.mjs",
},
{ global: "current" }
);
Turning a Script into a Module
Before you start, check whether the script declares globals outside a { }
block. If other scripts use them, the module exports them and browser.js
loads it lazily (see Keep the Script’s Globals).
Choose Where the Module Runs
Custom Elements
Custom elements should be defined in a per-window module (.mjs), imported
with { global: "current" } from the line that loaded the script.
tabgroup.mjs
and tabs.mjs are
examples.
Note
An element class must extend the window’s own HTMLElement or
MozXULElement. A system module that declares
class extends HTMLElement gets the system global’s HTMLElement instead.
customElements.define accepts that class, but the element never upgrades,
and calling the constructor throws NS_ERROR_UNEXPECTED.
Other Code
For code that isn’t an element, a system module (.sys.mjs) is typically best.
A process has one instance of each system module. The module takes the window
as a parameter where it needs one.
Tabbrowser.sys.mjs
is an example: Tabbrowser.create(window) runs for each new window.
BrowserComponents.manifest
registers that call under a browser-window- category instead of a loadSubScript call
(see Category manager indirection (callModulesFromCategory)).
A system module has none of the window’s globals, such as gBrowser or
document. Import each module it uses, and read the rest from the window it
received. If the script uses many window globals, use a per-window module
instead.
Keep the Script’s Globals
The module exports each global that other scripts use, and browser.js
defines a lazy getter for it with { global: "current" }, as shown in
How the Scripts Load. Other scripts keep reading the
globals by name. In the same commit:
list each global in browser.js.globals, which the no-more-globals rule checks;
declare each global in browser-window-globals.d.ts and browser-window.d.ts, so TypeScript sees it;
remove the script’s entry from the
globals-browser-windowblock.
status-panel.mjs is an example.
Keep the File’s History
If the script has no { } block, its indentation doesn’t change, so you can
rename it and turn it into a module in one commit (see
Commit 2: Turn the Script into a Module).
Otherwise, removing the block changes the indentation of every line. Git then
doesn’t recognize the file as renamed, so git log --follow and git blame
won’t show the history. To keep it, land the conversion as two commits, one
that renames the file and one that turns it into a module. A follow-up patch
then tells git blame to skip the second commit.
Commit 1: Rename the Script
Rename the script with this command:
git mv path/to/script.js path/to/script.mjs
Update its loadSubScript line, its jar.mn entry and any
globals-browser-window entry. loadSubScript ignores the file extension, so
the script still loads as before.
If the script’s file name is in the MAPPINGS table of the browser-window
environment, update that entry too, along with the script’s entry in the
support-files list of tools/lint/eslint.yml. ESLint looks up a
script in MAPPINGS by its .js name. Without the update, ESLint can’t find the
renamed script and fails on every browser-window file.
The .mjs extension turns on no-shadow with builtinGlobals. So a local
variable named after a DOM global, such as name or parent, becomes an
error. Rename those variables in this commit, and lint it before you go on:
./mach lint path/to/script.mjs
Commit 2: Turn the Script into a Module
Remove the { } block if there is one, and add export to the class or the
shared globals. Replace the loadSubScript line with
ChromeUtils.importESModule, or with a lazy getter in browser.js for a
script with shared globals. Remove any MAPPINGS and support-files entries
for the script, since ESLint no longer reads its globals. In the same commit,
give the module its lint globals (see
Give the Module Its Lint Globals) and
update the module paths (see Update the Module Paths).
Ask reviewers to read this commit with git diff -w.
These changes can’t be split. export can’t appear inside the block. Once the
block is gone, ESLint reads the file’s top-level names from its loadSubScript
line and defines them as globals in the same file. no-shadow then reports
each declaration, until the switch to importESModule removes its
loadSubScript line.
Follow-up Patch: Ignore the Reindent
Once commit 2 has landed, add it to .git-blame-ignore-revs and .hg-annotate-ignore-revs. The entries take the commit’s landed hashes, so commit 2 can’t include them.
git blame then attributes the lines that commit 2 really changed, such as
the export lines, to earlier commits. Check with git show -w that those
lines are a small part of the commit before you add the entry. (In the
conversions of the tab strip, tab and tab group elements, they were 22 to 47
lines out of 1,760 to 2,976.)
Give the Module Its Lint Globals
A per-window module imports each system module it uses, and names the window
globals it reads in a /* global … */ comment. tabgroup.mjs starts like
this:
/* global gBrowser, MozXULElement */
const { TabMetrics } = ChromeUtils.importESModule(
"moz-src:///browser/components/tabbrowser/TabMetrics.sys.mjs"
);
Keep system modules out of the comment. ESLint can’t tell when a name in the comment stops being a window global, but an import fails as soon as its module is gone.
Don’t add the module to the globals-browser-window block. That entry gives
the module every browser-window global, so each import of a system module that
the window also loads becomes a no-shadow error.
Update the Module Paths
If another file imports the module’s types, the module’s chrome:// URL needs
an entry in the generated type definitions (see
Updating Gecko Type Definitions).
Run this command to regenerate them:
./mach ts update
TypeScript checks the module only if the tsconfig.json of its directory
includes it (see
Custom Elements).
Getting Help
If you get stuck, ask in the Firefox Frontend channel (#frontend:mozilla.org) on Matrix.