ESModules.md

ECMAScript Modules

This documentation is inspired by Node.js' documentation on ECMAScript modules.

ECMAScript Modules or "ES modules" are the official ECMAScript standard for importing, exporting, and reusing JavaScript code.

ES modules can export function, class, const, let, and var statements using the export keyword.

// animalSounds.js
export function bark(num) {
  log('bark');
}

export const ANIMALS = ['dog', 'cat'];

Other ES modules can then import those declarations using import statements like the one below.

// main.js
import { ANIMALS, bark } from './animalSounds.js';

// Logs 'bark'
bark();

// Logs 'dog, cat'
log(ANIMALS);

Loading ES Modules

Command Line

From the command line ES modules can be loaded with the -m flag:

gjs -m module.js

JavaScript

ES modules cannot be loaded from strings at this time.

Besides the import expression syntax described above, Dynamic import() statements can be used to load modules from any GJS script or module.

import('./animalSounds.js').then((module) => {
    // module.default is the default export
    // named exports are accessible as properties
    // module.bark
}).catch(logError)

Because import() is asynchronous, you will need a mainloop running.

C API

Using the C API in gjs.h, ES modules can be loaded from a file or resource using gjs_load_module_file().

Shebang

example.js

#!/usr/bin/env -S gjs -m

import GLib from 'gi://GLib';
log(GLib);

chmod +x example.js
./example.js

import Specifiers

Terminology

The specifier of an import statement is the string after the from keyword, e.g. 'path' in import { sep } from 'path'. Specifiers are also used in export from statements, and as the argument to an import() expression.

There are three types of specifiers:

• Relative specifiers like './window.js'. They refer to a path relative to the location of the importing file. The file extension is always necessary for these.

• Bare specifiers like 'some-package'. In GJS bare specifiers typically refer to built-in modules like gi.

• Absolute specifiers like 'file:///usr/share/gjs-app/file.js'. They refer directly and explicitly to a full path or library.

Bare specifier resolutions import built-in modules. All other specifier resolutions are always only resolved with the standard relative URL resolution semantics.

Mandatory file extensions

A file extension must be provided when using the import keyword to resolve relative or absolute specifiers. Directory files (e.g. './extensions/__init__.js') must also be fully specified.

The recommended replacement for directory files (__init__.js) is:

'./extensions.js'
'./extensions/a.js'
'./extensions/b.js'

Because file extensions are required, folders and .js files with the same "name" should not conflict as they did with imports.

URLs

ES modules are resolved and cached as URLs. This means that files containing special characters such as # and ? need to be escaped.

file:, resource:, and gi: URL schemes are supported. A specifier like 'https://example.com/app.js' is not supported in GJS.

file: URLs

Modules are loaded multiple times if the import specifier used to resolve them has a different query or fragment.

import './foo.js?query=1'; // loads ./foo.js with query of "?query=1"
import './foo.js?query=2'; // loads ./foo.js with query of "?query=2"

The root directory may be referenced via file:///.

gi: Imports

gi: URLs are supported as an alternative means to load GI (GObject Introspected) modules.

gi: URLs support declaring libraries' versions. An error will be thrown when resolving imports if multiple versions of a library are present and a version has not been specified. The version is cached, so it only needs to be specified once.

import Gtk from 'gi://Gtk?version=4.0';
import Gdk from 'gi://Gdk?version=4.0';
import GLib from 'gi://GLib';
// GLib, GObject, and Gio are required by GJS so no version is necessary.

It is recommended to create a "version block" at your application's entry point.

import 'gi://Gtk?version=3.0'
import 'gi://Gdk?version=3.0'
import 'gi://Hdy?version=1.0'

After these declarations, you can import the libraries without version parameters.

import Gtk from 'gi://Gtk';
import Gdk from 'gi://Gdk';
import Hdy from 'gi://Hdy';

Built-in modules

Built-in modules provide a default export with all their exported functions and properties. Most modules provide named exports too. cairo does not provide named exports of its API.

Modifying the values of the default export does not change the values of named exports.

import system from 'system';
system.exit(1);

import { ngettext as _ } from 'gettext';
_('Hello!');

import.meta

• {Object}

The import.meta meta property is an Object that contains the following properties:

import.meta.url

• {string} The absolute file: or resource: URL of the module.

This is identical to Node.js and browser environments. It will always provide the URI of the current module.

This enables useful patterns such as relative file loading:

import Gio from 'gi://Gio';
const file = Gio.File.new_for_uri(import.meta.url);
const data = file.get_parent().resolve_relative_path('data.json');
const [, contents] = data.load_contents(null);

or if you want the path for the current file or directory

import GLib from 'gi://GLib';
const [filename] = GLib.filename_from_uri(import.meta.url);
const dirname = GLib.path_get_dirname(filename);

Interoperability with legacy imports modules

Because imports is a global object, it is still available in ES modules. It is not recommended to purposely mix import styles unless absolutely necessary.

import statements

An import statement can only reference an ES module. import statements are permitted only in ES modules, but dynamic import() expressions is supported in legacy imports modules for loading ES modules.

When importing legacy imports modules, all var declarations are provided as properties on the default export.

Differences between ES modules and legacy imports modules

No imports and var exports

You must use the export syntax instead.

No meta path properties

These imports properties are not available in ES modules:

• __modulePath__
• __moduleName__
• __parentModule__

__modulePath__, __moduleName__ and __parentModule__ use cases can be replaced with import.meta.url.