GNOME JavaScript Introduction
Welcome to GNOME JavaScript (GJS)! This first page details key differences from other JavaScript frameworks you've used in the past.
Imports and Modules
In GJS every file is treated as a "module" and any variable declared as using 'var' (or global scope) is exported. Each "module" is imported using the 'imports' object using the pattern imports.[fileName] where the file's literal name is fileName.js. If your fileName contains a character that is not a valid JavaScript identifier you can access it using the object+key syntax: object['fileName'].
a.js:
var A = class A {};
b.js:
Standard Syntax
const A = imports.a;
let a = new A.A();
2
Quick Object Syntax
const { A } = imports.a;
let a = new A();
2
Modules are searched in paths defined in the array imports.searchPath
. You can modify the value of imports.searchPath
to include the directories where to look for modules.
Import Versioning
In A GTK+ Application
Use pkg.require({})
Elsewhere
Use imports.gi.Versions.Gtk = X;
Logging
TIP
Some distributions may require you to be part of a systemd
user group to access logs. On systems that are not using systemd
, logs may be written to ~/.xsession-errors
.
GJS has a number of logging facilities, some particular to GJS, others inherited from JavaScript and a few that are provided by GLib. There is more complete documentation available for Built-in Loggingopen in new window and the console
open in new window suite of functions.
console
Functions
As of GJS 1.70 (GNOME 41), the console
collection of functions are available as described in the WHATWG Console Standardopen in new window. The console
object is available globally and should be familiar to those that have used JavaScript in web development.
Note that the console
functions do not work with the GNOME_SHELL_EXTENSION_UUID
feature, so if you rely on this you should use the built-in functions instead.
Built-in Functions
GJS also has a number of built-in logging functions:
// Log a string, usually to `journalctl`
log('a message');
// Log an Error() with a stack trace and optional prefix
try {
throw new Error('An error occurred');
} catch (e) {
logError(e, 'ExtensionError');
}
// Print a message to stdout
print('a message');
// Print a message to stderr
printerr('An error occured');
2
3
4
5
6
7
8
9
10
11
12
13
14
15
When writing extensions, print()
and printerr()
are not particularly useful since we won't have easy access to gnome-shell
's stdin
and stderr
pipes. Instead you will want use log()
and logError()
and watch the log in a new terminal with journalctl
:
$ journalctl -f -o cat /usr/bin/gnome-shell
Extending GObject Classes
GJS supports native ES6 classes but requires a few changes to any class that extends from a GObject class (a subclass of a GTK+ widget or of a GLib class for instance).
Standard ES6 Class
var A = class A extends B {
constructor(x, y){
super(x);
this.y = y;
}
}
2
3
4
5
6
GObject Subclass
var A = GObject.registerClass(
{
GTypeName: 'A',
},
class A extends GObject.Object {
constructor(x, y) {
super(x);
this.y = y;
}
}
);
2
3
4
5
6
7
8
9
10
11