GNOME JavaScript (GJS) Application Development

Technology Stack

Component	Purpose
GJS	JavaScript runtime (SpiderMonkey) with GObject Introspection bindings
GTK 4	UI toolkit
Libadwaita (Adw) 1.x	GNOME-specific widgets, adaptive layouts, styling
GLib / GIO	Core utilities, async I/O, settings, D-Bus, file operations
Meson	Build system
Flatpak	App packaging and distribution
Blueprint (optional)	Declarative UI markup that compiles to GTK XML

Imports (ES Modules — required for new code)

// Built-in GJS modules
import Cairo from "cairo";
import Gettext from "gettext";
import System from "system";

// Platform libraries via gi:// URI
import GLib from "gi://GLib";
import GObject from "gi://GObject";
import Gio from "gi://Gio";

// Versioned imports (required when multiple API versions exist)
import Gtk from "gi://Gtk?version=4.0";
import Adw from "gi://Adw?version=1";

// Relative user modules (include .js extension)
import * as Utils from "./lib/utils.js";

Keep imports grouped: built-in → platform (gi://) → local, separated by blank lines. Use PascalCase for imported modules.

GObject Subclassing

Register every GObject subclass with GObject.registerClass(). Use constructor() (not _init(), which is legacy pre-GNOME 42).

const MyWidget = GObject.registerClass(
  {
    GTypeName: "MyWidget",
    Template: "resource:///com/example/MyApp/my-widget.ui",
    InternalChildren: ["title_label", "action_button"],
    Properties: {
      "example-prop": GObject.ParamSpec.string(
        "example-prop",
        "",
        "",
        GObject.ParamFlags.READWRITE,
        null,
      ),
    },
    Signals: {
      "item-selected": {
        param_types: [GObject.TYPE_STRING],
      },
    },
  },
  class MyWidget extends Gtk.Box {
    constructor(params = {}) {
      super(params);
      // Template children: this._title_label, this._action_button
    }

    get example_prop() {
      return this._example_prop ?? null;
    }

    set example_prop(value) {
      if (this.example_prop === value) return;
      this._example_prop = value;
      this.notify("example-prop");
    }
  },
);

Key rules:

• Property names: kebab-case in GObject declarations, snake_case in JS accessors
• Always call this.notify('prop-name') in setters to emit change notifications
• GTypeName is optional unless the type is referenced in UI XML <template class="...">
• InternalChildren maps id attrs in UI XML → this._childId; Children → this.childId

Application Entry Point

import GLib from "gi://GLib";
import GObject from "gi://GObject";
import Gio from "gi://Gio";
import Gtk from "gi://Gtk?version=4.0";
import Adw from "gi://Adw?version=1";

import { MyAppWindow } from "./window.js";

const MyApp = GObject.registerClass(
  class MyApp extends Adw.Application {
    constructor() {
      super({
        application_id: "com.example.MyApp",
        flags: Gio.ApplicationFlags.DEFAULT_FLAGS,
      });

      const quitAction = new Gio.SimpleAction({ name: "quit" });
      quitAction.connect("activate", () => this.quit());
      this.add_action(quitAction);
      this.set_accels_for_action("app.quit", ["<Primary>q"]);
    }

    vfunc_activate() {
      let win = this.active_window;
      if (!win) win = new MyAppWindow(this);
      win.present();
    }
  },
);

const app = new MyApp();
app.run([System.programInvocationName, ...ARGV]);

Async with Gio._promisify

Wrap *_async/*_finish pairs once at module level for async/await usage:

Gio._promisify(
  Gio.File.prototype,
  "load_contents_async",
  "load_contents_finish",
);

const file = Gio.File.new_for_path("/tmp/example.txt");
try {
  const [contents] = await file.load_contents_async(null);
  const text = new TextDecoder().decode(contents);
} catch (e) {
  logError(e, "Failed to load file");
}

Code Style (GJS conventions)

• 4-space indentation, single quotes, semicolons
• const by default, let when mutation needed, never var
• File names: lowerCamelCase.js; directories: lowercase
• Arrow functions for inline callbacks; .bind(this) for method references
• export for public API, never var

Reference Files

Consult these based on the task at hand:

• Project setup & packaging: references/project-setup.md — Meson build, Flatpak manifests, GResource, application ID, desktop files, GSettings schemas, directory layout
• UI design (GTK4 + Libadwaita): references/ui-patterns.md — Widget templates (UI XML), adaptive layouts (breakpoints, split views, view switcher), boxed lists, style classes, header bars, GNOME HIG patterns
• GIO & platform patterns: references/gio-patterns.md — File I/O, GSettings, actions & menus, D-Bus, subprocesses, list models, GVariant