Skip to content
Noctalia Noctalia

Plugin Development Overview

Noctalia Shell features a powerful plugin system that allows you to extend the shell with custom functionality. Plugins are written in QML and can integrate seamlessly with the shell’s UI and services.

What Can Plugins Do?

Section titled “What Can Plugins Do?”

Plugins can provide several types of components, each serving different purposes:

Bar Widgets

Section titled “Bar Widgets”

Add custom widgets to the top/bottom bar that provide quick access to information and actions.

Use cases:

  • Display system information (CPU, memory, network)
  • Show custom indicators (notifications, status)
  • Quick action buttons (launcher, shortcuts)
  • Status monitors (battery, time, weather)

Learn more: Bar Widget Development

Panels

Section titled “Panels”

Create full-screen overlay panels that can be opened from bar widgets or triggered programmatically.

Use cases:

  • Detailed information displays
  • Complex UI interactions
  • Configuration interfaces
  • Content browsers and lists

Learn more: Panel Development

Main Component

Section titled “Main Component”

Run background logic and handle IPC (Inter-Process Communication) commands. Optional component for plugins that need background processing.

Use cases:

  • Process external commands via IPC
  • Monitor system events
  • Perform background tasks
  • Integrate with external services

Learn more: IPC Guide

Settings UI

Section titled “Settings UI”

Provide a settings interface that integrates with Noctalia’s settings panel, allowing users to configure your plugin.

Use cases:

  • User configuration
  • Plugin customization
  • Feature toggles
  • Preferences management

Learn more: Settings UI Guide (coming soon)

Plugin Architecture

Section titled “Plugin Architecture”

Plugins in Noctalia follow a modular architecture:

your-plugin/
├── manifest.json      # Plugin metadata (required)
├── preview.png        # Preview image for plugin gallery (optional, recommended)
├── Main.qml           # Background logic with IPC handlers (optional)
├── BarWidget.qml      # Bar widget component (optional)
├── Panel.qml          # Panel overlay component (optional)
├── Settings.qml       # Settings UI component (optional)
├── settings.json      # User settings data (auto-generated)
├── i18n/              # Translations (optional)
│   ├── en.json
│   └── es.json
└── README.md          # Plugin documentation

Plugin Lifecycle

Section titled “Plugin Lifecycle”
  1. Installation: Plugin is downloaded from a registry to ~/.config/noctalia/plugins/
  2. Registration: PluginRegistry scans the folder and validates the manifest
  3. Enabling: User enables the plugin in settings
  4. Loading: PluginService loads the plugin components and injects the Plugin API
  5. Running: Plugin components receive pluginApi property with access to services
  6. Settings: Users can configure the plugin through the integrated settings UI
  7. Unloading: When disabled, the plugin is cleanly unloaded
  8. Uninstallation: Plugin folder is removed from disk

Plugin API

Section titled “Plugin API”

Every plugin component receives a pluginApi object that provides access to plugin functionality and Noctalia services.

Core Properties

Section titled “Core Properties”
  • pluginId - Unique plugin identifier
  • pluginDir - Plugin directory path
  • pluginSettings - User settings object (read/write)
  • manifest - Plugin manifest data
  • currentLanguage - Current UI language code
  • mainInstance - Reference to the instantiated Main.qml component (null if not loaded)
  • barWidget - Reference to the bar widget Component (null if not provided)

Core Functions

Section titled “Core Functions”
  • saveSettings() - Persist settings to disk
  • openPanel(screen) - Open the plugin’s panel
  • closePanel(screen) - Close the plugin’s panel
  • tr(key, interpolations) - Translate text
  • trp(key, count, ...) - Translate with plurals
  • hasTranslation(key) - Check if translation exists

Noctalia Services

Section titled “Noctalia Services”

Plugins have full access to Noctalia’s service ecosystem:

qs.Commons - Core utilities

  • Settings - Global Noctalia settings
  • I18n - Internationalization
  • Logger - Logging utilities
  • Style - Design system constants
  • Color - Theme-aware colors

qs.Services.UI - UI services

  • ToastService - Toast notifications
  • PanelService - Panel management
  • TooltipService - Tooltip display

qs.Services.System - System services

  • AudioService - Audio control
  • BatteryService - Battery information
  • NetworkService - Network status
  • And many more…

qs.Widgets - UI components

  • NButton, NIcon, NText, NTextInput
  • NScrollView, NColorPicker, and more

Full API Reference

For complete API documentation, see the Plugin API Reference.

Learning Path

Section titled “Learning Path”

Follow this recommended path to master plugin development:

  1. Getting Started - Create your first plugin

    • Set up your development environment
    • Create a basic bar widget
    • Understand the plugin structure

  2. Manifest Reference - Understand plugin configuration

    • Learn all manifest fields
    • Configure entry points
    • Set up default settings

  3. Bar Widget Development - Build bar widgets

    • Create interactive widgets
    • Handle user interactions
    • Style with Noctalia’s design system

  4. Panel Development - Create overlay panels

    • Build full-screen interfaces
    • Handle panel lifecycle
    • Create complex UIs

  5. Plugin API Reference - Master the API

    • Complete API documentation
    • Service integration
    • Advanced patterns

  6. IPC Guide - Background processing

    • Create IPC handlers
    • Handle external commands
    • Integrate with scripts and keybindings

  7. Additional Topics (coming soon)

Example Plugins

Section titled “Example Plugins”

Explore these example plugins in the official repository to see real-world implementations:

  • hello-world - Demonstrates all plugin features (bar widget, panel, settings, IPC)
  • launcher-button - Simple bar widget that opens the app launcher
  • privacy-indicator - Shows when mic/camera/screen sharing is active

Next Steps

Section titled “Next Steps”

Ready to start building? Head to the Getting Started guide to create your first plugin in just a few minutes!