# Quickshell Plugin manifest.json Structure in Omarchy: Complete Schema Guide

> Understand the Quickshell plugin manifest.json structure in Omarchy. Learn about schemaVersion, id, kinds, and entryPoints for QML functionality. Get the complete schema guide now.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: api-reference
- Published: 2026-08-24

---

**A Quickshell plugin manifest.json requires `schemaVersion` 1, a unique `id`, `kinds` array, and `entryPoints` mapping to declare which QML files implement bar, panel, service, or OSD functionality.**

In the basecamp/omarchy repository, every Quickshell plugin includes a lightweight JSON manifest that sits alongside its QML source files. Understanding the exact Quickshell plugin manifest.json structure ensures the Omarchy shell can correctly discover, categorize, and load your extensions at runtime.

## Core manifest.json Schema Fields

The manifest uses a fixed schema where `schemaVersion` is always set to **1**. This version signals to the loader how to parse the remaining metadata.

### Required Metadata Identifiers

Every manifest must declare these top-level fields:

- **`id`** – A unique string identifier, conventionally prefixed with `omarchy.` (e.g., `omarchy.bar` or `omarchy.wifiqr`).
- **`name`** – The human-readable title displayed in plugin menus and UI pickers.
- **`version`** – Semantic version of the plugin itself (e.g., `"1.0.0"`).
- **`author`** – The individual or organization responsible for maintaining the plugin.
- **`description`** – A brief summary shown when users browse available plugins.

### Declaring Plugin Kinds and Entry Points

The **`kinds`** field is an array of strings that categorizes what the plugin provides. Valid values include `bar`, `panel`, `service`, `osd`, and `notification`.

The **`entryPoints`** object maps each kind to its corresponding QML implementation file. The keys must match entries in the `kinds` array exactly.

```json
{
  "schemaVersion": 1,
  "id": "omarchy.example",
  "name": "Example Plugin",
  "kinds": ["panel", "service"],
  "entryPoints": {
    "panel": "Panel.qml",
    "service": "Service.qml"
  }
}

```

As implemented in basecamp/omarchy, the heavy lifting—logic, DBus calls, and UI rendering—lives in these QML files referenced by `entryPoints`, while the manifest merely declares the interface.

## Optional manifest.json Configuration

Beyond the core schema, manifests support extended fields for complex plugins.

### Dependencies and Assets

Use the **`dependencies`** array to list plugin IDs that must load before yours. The **`assets`** object exposes non-QML resources like icons or images.

```json
{
  "dependencies": ["omarchy.network"],
  "assets": {
    "icon": "icons/plugin.svg"
  }
}

```

### Hooks and Default Settings

The **`hooks`** object defines lifecycle functions the shell can invoke, such as `onLoad` or `onUnload`. The **`settings`** object provides default configuration values that the shell exposes to users.

```json
{
  "hooks": {
    "onLoad": "initFunction"
  },
  "settings": {
    "refreshInterval": 5,
    "theme": "dark"
  }
}

```

## Real-World Examples from basecamp/omarchy

Examining the source repository reveals how these fields combine in production plugins.

### Bar Plugin Manifest

In [`shell/plugins/bar/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/bar/manifest.json), the built-in bar plugin declares itself as a single-kind component:

```json
{
  "schemaVersion": 1,
  "id": "omarchy.bar",
  "name": "Omarchy Bar",
  "version": "1.0.0",
  "author": "Basecamp",
  "description": "Main status bar",
  "kinds": ["bar"],
  "entryPoints": {
    "bar": "Bar.qml"
  }
}

```

### Wi-Fi QR Panel Manifest

The Wi-Fi QR panel in [`shell/plugins/panels/wifiqr/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/panels/wifiqr/manifest.json) demonstrates a focused panel implementation:

```json
{
  "schemaVersion": 1,
  "id": "omarchy.wifiqr",
  "name": "Wi-Fi QR Code",
  "version": "1.0.0",
  "author": "Basecamp",
  "description": "Display Wi-Fi credentials as QR code",
  "kinds": ["panel"],
  "entryPoints": {
    "panel": "WifiQr.qml"
  }
}

```

## Minimal Plugin Manifest Template

To create a new panel plugin from scratch, place the following in [`shell/plugins/panels/mywidget/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/panels/mywidget/manifest.json):

```json
{
  "schemaVersion": 1,
  "id": "omarchy.mywidget",
  "name": "My Widget",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A simple example panel",
  "kinds": ["panel"],
  "entryPoints": {
    "panel": "MyWidget.qml"
  }
}

```

Ensure `MyWidget.qml` resides in the same directory; the Omarchy loader resolves paths relative to the manifest location.

## Advanced Multi-Kind Configuration

Plugins providing both background services and visual components declare multiple kinds with separate QML entry points:

```json
{
  "schemaVersion": 1,
  "id": "omarchy.myservice",
  "name": "My Service",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "Provides a background service and an on-screen display",
  "kinds": ["service", "osd"],
  "entryPoints": {
    "service": "MyService.qml",
    "osd": "MyOsd.qml"
  },
  "dependencies": ["omarchy.network"]
}

```

The `dependencies` array guarantees that `omarchy.network` initializes before this plugin attempts to use network-related functionality.

## Summary

- The Quickshell plugin manifest.json structure requires `schemaVersion` set to **1** and uses a fixed schema understood by the Omarchy runtime.
- Required fields include `id` (prefixed with `omarchy.`), `name`, `version`, `kinds` (array), and `entryPoints` (object mapping kinds to QML files).
- Valid kinds are `bar`, `panel`, `service`, `osd`, and `notification`.
- Optional fields like `dependencies`, `assets`, `hooks`, and `settings` enable complex plugin hierarchies and resource management.
- Manifests live adjacent to their QML files, as seen in [`shell/plugins/bar/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/bar/manifest.json) and [`shell/plugins/panels/wifiqr/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/panels/wifiqr/manifest.json).

## Frequently Asked Questions

### What schema version does Omarchy use for Quickshell manifests?

The basecamp/omarchy repository currently uses **schema version 1** for all plugin manifests. This version number must appear exactly as `"schemaVersion": 1` at the root of every manifest.json file.

### Can a single Quickshell plugin implement multiple UI components?

Yes. Define multiple entries in the `kinds` array—such as `["service", "osd"]`—and map each to its respective QML file in the `entryPoints` object. The shell instantiates each component according to its kind and lifecycle requirements.

### Where should the manifest.json file be located?

Place [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) in the plugin's root directory alongside its QML implementation files. For example, [`shell/plugins/panels/mywidget/manifest.json`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/panels/mywidget/manifest.json) should sit next to `MyWidget.qml` so relative paths in `entryPoints` resolve correctly.

### How does Omarchy handle plugin loading order?

Declare dependencies using the `dependencies` array, listing plugin IDs as strings. The Omarchy loader guarantees that every plugin listed in `dependencies` initializes before the dependent plugin begins loading, preventing undefined reference errors at runtime.