Manifest Reference

Every Noctalia plugin must include a manifest.json file that describes the plugin and its capabilities.

Complete Example

{
  "id": "my-plugin",
  "name": "My Awesome Plugin",
  "version": "1.2.3",
  "minNoctaliaVersion": "3.6.0",
  "author": "Your Name",
  "license": "MIT",
  "repository": "https://github.com/noctalia-dev/legacy-v4-plugins",
  "description": "A comprehensive example plugin demonstrating all features",
  "entryPoints": {
    "main": "Main.qml",
    "barWidget": "BarWidget.qml",
    "desktopWidget": "DesktopWidget.qml",
    "desktopWidgetSettings": "DesktopWidgetSettings.qml",
    "controlCenterWidget": "ControlCenterWidget.qml",
    "launcherProvider": "LauncherProvider.qml",
    "panel": "Panel.qml",
    "settings": "Settings.qml"
  },
  "dependencies": {
    "plugins": ["other-plugin"]
  },
  "metadata": {
    "commandPrefix": "mycommand",
    "defaultSettings": {
      "enabled": true,
      "customValue": "hello"
    }
  }
}

Required Fields

`id`

Type: String
Required: Yes
Description: Unique identifier for your plugin
Rules:
Must match the plugin directory name
Use lowercase with hyphens (kebab-case)
Should be globally unique
Cannot be changed after publication

Example: "my-plugin", "privacy-indicator", "launcher-button"

`name`

Type: String
Required: Yes
Description: Human-readable plugin name displayed in the UI

Example: "Privacy Indicator", "Hello World"

`version`

Type: String
Required: Yes
Format: Semantic versioning (x.y.z)
Description: Plugin version number
Rules:
Must follow semantic versioning
Format: MAJOR.MINOR.PATCH
Used for update detection

Example: "1.0.0", "2.3.1"

`author`

Type: String
Required: Yes
Description: Plugin author name or organization

Example: "Noctalia Team", "John Doe"

`description`

Type: String
Required: Yes
Description: Brief description of what the plugin does
Recommendation: Keep under 100 characters

Example: "A privacy indicator widget that shows when microphone, camera, or screen sharing is active."

Optional Fields

`minNoctaliaVersion`

Type: String
Default: No minimum
Format: Semantic versioning (x.y.z)
Description: Minimum Noctalia Shell version required

Example: "3.6.0"

Tip Always specify minNoctaliaVersion to ensure compatibility with your plugin’s required APIs.

`license`

Type: String
Default: None
Description: SPDX license identifier
Common values: "MIT", "GPL-3.0", "Apache-2.0"

Example: "MIT"

`repository`

Type: String (URL)
Default: None
Description: Git repository URL for your plugin

Example: "https://github.com/noctalia-dev/legacy-v4-plugins"

Entry Points

The entryPoints object specifies which components your plugin provides. All entry points are optional, but you must provide at least one.

{
  "entryPoints": {
    "main": "Main.qml",
    "barWidget": "BarWidget.qml",
    "desktopWidget": "DesktopWidget.qml",
    "controlCenterWidget": "ControlCenterWidget.qml",
    "launcherProvider": "LauncherProvider.qml",
    "panel": "Panel.qml",
    "settings": "Settings.qml"
  }
}

`main`

File: Main.qml
Purpose: Background logic and IPC handlers
Use cases:
Process IPC commands
Run background tasks
Monitor system events
Provide services to other components

Example:

{
  "entryPoints": {
    "main": "Main.qml"
  }
}

See IPC Guide for details.

`barWidget`

File: BarWidget.qml
Purpose: Widget displayed in the top/bottom bar
Use cases:
Display system information
Show indicators
Provide quick actions
Open panels on click

Example:

{
  "entryPoints": {
    "barWidget": "BarWidget.qml"
  }
}

See Bar Widget Guide for details.

`desktopWidget`

File: DesktopWidget.qml
Purpose: Draggable widget on the desktop background
Use cases:
Display at-a-glance information
Clock, weather, or media displays
Audio visualizers
Decorative elements

Example:

{
  "entryPoints": {
    "desktopWidget": "DesktopWidget.qml"
  }
}

See Desktop Widget Guide for details.

`desktopWidgetSettings`

File: DesktopWidgetSettings.qml
Purpose: Per-instance settings UI for desktop widgets
Use cases:
Configure individual widgets
Per-instance options that differ from plugin-wide settings

Example:

{
  "entryPoints": {
    "desktopWidgetSettings": "DesktopWidgetSettings.qml"
  }
}

Tip If desktopWidgetSettings is not defined, the system falls back to the settings entrypoint (if available) when the user opens the widget settings from the context menu.

See Desktop Widget Guide for details.

`controlCenterWidget`

File: ControlCenterWidget.qml
Purpose: Button widget in the Control Center panel
Use cases:
Quick toggle actions
Open plugin panels
System shortcuts

Example:

{
  "entryPoints": {
    "controlCenterWidget": "ControlCenterWidget.qml"
  }
}

See Control Center Widget Guide for details.

`launcherProvider`

File: LauncherProvider.qml
Purpose: Search/browse provider for the launcher
Use cases:
Custom search sources
Command handlers (e.g., >kaomoji)
Category-based browsing

Example:

{
  "entryPoints": {
    "launcherProvider": "LauncherProvider.qml"
  },
  "metadata": {
    "commandPrefix": "mycommand"
  }
}

Tip When providing a launcher provider, set commandPrefix in metadata to define the >prefix command. This is also used by pluginApi.toggleLauncher() for IPC integration. See IPC Guide for details.

See Launcher Provider Guide for details.

`panel`

File: Panel.qml
Purpose: Full-screen overlay panel
Use cases:
Detailed information display
Complex UI interactions
Configuration interfaces
Content browsers

Example:

{
  "entryPoints": {
    "panel": "Panel.qml"
  }
}

See Panel Guide for details.

`settings`

File: Settings.qml
Purpose: Settings UI integrated into Noctalia Settings
Use cases:
User configuration
Plugin customization
Feature toggles
Preferences

Example:

{
  "entryPoints": {
    "settings": "Settings.qml"
  }
}

Coming Soon Settings Guide - Learn how to create configuration interfaces for your plugin.

Dependencies

Specify plugin dependencies in the dependencies object.

{
  "dependencies": {
    "plugins": ["other-plugin", "required-plugin"]
  }
}

`plugins`

Type: Array of plugin IDs
Default: []
Description: List of plugin IDs that must be installed for this plugin to work

Example:

{
  "dependencies": {
    "plugins": []
  }
}

Note Plugin dependency resolution is not yet implemented. This field is reserved for future use.

Metadata

The metadata object contains additional plugin information.

{
  "metadata": {
    "commandPrefix": "mycommand",
    "defaultSettings": {
      "message": "Hello World",
      "backgroundColor": "#A9AEFE",
      "enabled": true,
      "updateInterval": 1000
    }
  }
}

`commandPrefix`

Type: String
Default: Plugin ID
Description: The command prefix used to activate this plugin’s launcher provider
Purpose:
Defines the >prefix command that activates your launcher provider
Used by pluginApi.toggleLauncher() to pre-fill the search text
Falls back to the plugin ID if not specified

Usage:

{
  "metadata": {
    "commandPrefix": "kaomoji"
  }
}

With the above, the launcher command would be >kaomoji and pluginApi.toggleLauncher() would open the launcher with >kaomoji pre-filled.

Tip Set commandPrefix when your desired command is shorter or different from your plugin ID. For example, the calibre-provider plugin uses "commandPrefix": "cb" so users type >cb instead of >calibre-provider.

`defaultSettings`

Type: Object
Default: {}
Description: Default values for plugin settings
Purpose:
Provide initial values when plugin is first enabled
Serve as fallback when settings file doesn’t exist
Document available settings

Usage in plugin:

// Get value from settings with fallback to default
readonly property string message:
  pluginApi?.pluginSettings?.message ||
  pluginApi?.manifest?.metadata?.defaultSettings?.message ||
  ""

Supported types:

String: "hello"
Number: 42, 3.14
Boolean: true, false
Object: {"key": "value"}
Array: ["item1", "item2"]

Validation Rules

The PluginRegistry validates manifests with these rules:

Required fields: id, name, version, author, description, entryPoints
Version format: Must match x.y.z pattern (e.g., 1.0.0)
Entry points: At least one entry point must be specified
ID format: Should be lowercase with hyphens

Best Practices

Versioning

Start at 1.0.0 for initial release
Increment PATCH for bug fixes: 1.0.1
Increment MINOR for new features: 1.1.0
Increment MAJOR for breaking changes: 2.0.0

Description

Be concise (under 100 characters)
Focus on what the plugin does
Use proper capitalization
Avoid marketing language

Default Settings

Provide sensible defaults
Document all available settings
Use descriptive key names
Include comments in your code explaining settings

Repository

Link to the plugin’s source code
Include a README.md in your plugin directory
Maintain a changelog
Provide screenshots if applicable

Example Manifests

{
  "id": "simple-widget",
  "name": "Simple Widget",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A minimal bar widget",
  "entryPoints": {
    "barWidget": "BarWidget.qml"
  },
  "dependencies": {
    "plugins": []
  },
  "metadata": {
    "defaultSettings": {}
  }
}

Full-Featured Plugin

{
  "id": "hello-world",
  "name": "Hello World",
  "version": "1.0.0",
  "minNoctaliaVersion": "3.6.0",
  "author": "Noctalia Team",
  "license": "MIT",
  "repository": "https://github.com/noctalia-dev/legacy-v4-plugins",
  "description": "A simple Hello World plugin demonstrating functionalities.",
  "entryPoints": {
    "main": "Main.qml",
    "barWidget": "BarWidget.qml",
    "desktopWidget": "DesktopWidget.qml",
    "desktopWidgetSettings": "DesktopWidgetSettings.qml",
    "controlCenterWidget": "ControlCenterWidget.qml",
    "panel": "Panel.qml",
    "settings": "Settings.qml"
  },
  "dependencies": {
    "plugins": []
  },
  "metadata": {
    "defaultSettings": {
      "message": "Hello World",
      "backgroundColor": "#A9AEFE"
    }
  }
}

Complete Example

Required Fields

`id`

`name`

`version`

`author`

`description`

Optional Fields

`minNoctaliaVersion`

`license`

`repository`

Entry Points

`main`

`barWidget`

`desktopWidget`

`desktopWidgetSettings`

`controlCenterWidget`

`launcherProvider`

`panel`

`settings`

Dependencies

`plugins`

Metadata

`commandPrefix`

`defaultSettings`

Validation Rules

Best Practices

Versioning

Description

Default Settings

Repository

Example Manifests

Minimal Bar Widget

Full-Featured Plugin

See Also