Gnome extension development

Documentation

Official documentation

GNOME Shell Extensions

Overview

Anatomy of an Extension

Preferences and schema

Preferences

GObject (signals, etc)

The Basics of GObject

Development process

(https://gjs.guide/extensions/development/debugging.html)

Setup

  1. Modify the extension’s version number

    ⚠️ If you don’t do this first and you create a symlink (the next step), Gnome may automatically update the plugin, which will overwrite the entire directory. Here’s a workaround to prevent it:

    1. Open metadata.json

    2. Change version to something big (e.g. 1000)

  2. Symlink directory of extension to the Gnome Shell extensions directory, e.g.

    cd spotify-ad-blocker
ln -s $(pwd) ~/.local/share/gnome-shell/extensions/spotify-ad-block@danigm.net

Running and debugging in Wayland

⚠️ Unfortunately this method uses a separate DBUS session and many apps will not work inside the nested Gnome Shell, so you may need to use X server for developing some extensions if you want changes to the extension to refresh without having to log out of Gnome

  1. Run a nested instance of Gnome Shell

    dbus-run-session -- gnome-shell --nested --wayland

    ⓘ The Gnome logs will appear in this terminal, so you may find it useful to grep for the specific logs you want:

    dbus-run-session -- gnome-shell --nested --wayland 2>&1 | grep spotify-ad-blocker

    👉 When the shell first opens, it may open to the activities overview, capturing the mouse. If this happens, press Esc

  2. Open a terminal inside the nested Gnome Shell and enable the extension, e.g.

    gnome-extensions enable spotify-ad-block@danigm.net

  3. If you make changes to the extension, simply close the nested Gnome shell and repeat the above instructions to get the latest changes

Running and debugging in X server

  1. Enable the extension, e.g.

    gnome-extensions enable spotify-ad-block@danigm.net

  2. Use journalctl to see messages

    journalctl /usr/bin/gnome-shell -f

  3. If you make changes to the extension, restart Gnome Shell to pick up the changes

    1. Press Alt+F2

    2. Type r and press Enter

API documentation

imports.gi.*

See https://gjs-docs.gnome.org/

Alternatives:

imports.misc.*, imports.ui.*

See https://gitlab.gnome.org/GNOME/gnome-shell/-/tree/main/js