Gnome extension development

Development documentation

Official documentation

GNOME Shell Extensions

Development process

  1. 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

  2. Next, Gnome needs to load the extension

    (https://gjs.guide/extensions/development/creating.html#enabling-the-extension)

    The extension can’t be loaded or updated at runtime, so you have two choices:

    • If you’re using Wayland, run a nested instance of Gnome Shell
    dbus-run-session -- gnome-shell --nested --wayland
    • If you’re using X server, restart Gnome Shell
    killall -3 gnome-shell

  3. Enable the extension, e.g.

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

  4. (Optional) Modify the extension’s version number

    Gnome (or is it Gnome Extension Manager that does this?) may try to update the plugin, which will overwrite your changes. Here’s a workaround to prevent it:

    1. Open metadata.json

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

  5. After making changes to the extension, repeat the steps above (under Gnome needs to load the extension) so Gnome will reload the extension with the new changes

Debugging

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

  • Use console.log to log messages

  • To see messages

    journalctl /usr/bin/gnome-shell -f

Overview

Anatomy of an Extension

Preferences and schema

Preferences

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