> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qomicex.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Build your first plugin from scratch

## Build your first plugin from scratch

This tutorial walks you through creating a minimal working Qomicex plugin from scratch. **Starting from the `qomicex` CLI scaffold (Scaffold)is recommended** (it generates a valid project structure automatically). You can also write everything by hand; see the alternative below.

## Prerequisites

* Qomicex Launcher (Launcher)is installed (for testing)
* [qomicex CLI](https://docs.qomicex.top/en/plugins/cli.md) (Node.js ≥ 20):

```bash theme={null}
pnpm --filter @qomicex/cli build
pnpm --filter @qomicex/cli link   # link into PATH so you can call qomicex directly
```

Before your first use, run `qomicex doctor` to check whether Node / pnpm / the plugin project environment are ready (read-only, it modifies no files).

## 1. Generate a project with the CLI (recommended)

```bash theme={null}
qomicex create dev.example.helloworld
cd dev.example.helloworld
pnpm install
qomicex verify     # validate immediately and confirm 0 errors
```

The generated project uses a Vite + React 19 + TS + Tailwind project-based setup (see [React + Vite plugin development](https://docs.qomicex.top/en/plugins/react-plugin.md)), with `manifest.json` already in place:

```json theme={null}
{
  "id": "dev.example.helloworld",
  "name": "Hello World",
  "version": "0.1.0",
  "minLauncherVersion": "0.1.0",
  "layers": ["l2"],
  "permissions": ["config:read", "ui:toast", "network:cors_proxy"],
  "entry": { "frontend": "dist/index.html" }
}
```

Key fields:

* `id`: The unique plugin ID, which is also the install directory name (`plugins/{id}/`). **Never change it once published**
* `layers`: Layer declarations. Plugins with script pages should use `["l2", "l3"]` (**iframe sandbox rendering by default**; for inline rendering you must explicitly declare `"render": "inline"` in the manifest. Activation depends on whether `entry.frontend` exists; see [layers layer definitions](https://docs.qomicex.top/en/plugins/manifest.md#layers-layer-definitions))
* `permissions`: The permissions your plugin needs (see [Complete plugin API reference](https://docs.qomicex.top/en/plugins/plugin-api.md))
* `entry.frontend`: The plugin page entry, a relative path inside the `.qplugin` package

## 2. Write the plugin page

Create `src/App.tsx` (React) or modify it as needed. For plain HTML, write directly in `index.html`:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
</head>
<body>
  <div class="p-card">
    <div class="p-card-title">Hello, Qomicex!</div>
    <div class="p-card-desc">This is my first plugin.</div>
    <button id="btn" class="p-btn p-btn--primary">Click me</button>
  </div>

  <script>
    document.getElementById('btn').addEventListener('click', async function () {
      const settings = await window.__PLUGIN_API__.call('getSettings')
      window.__PLUGIN_API__.call('showToast', 'Setting count: ' + Object.keys(settings).length, 'success')
    })
  </script>
</body>
</html>
```

* Style with the `.p-*` component classes provided by the launcher (such as `.p-card` and `.p-btn`); they follow the light and dark themes automatically. See [UI component library](https://docs.qomicex.top/en/plugins/plugin-ui.md) for the full list.
* Plugin scripts talk to the launcher through the global `window.__PLUGIN_API__` object. Note that the script runs as soon as the plugin is activated (inline or in the L2 sandbox), without visiting the plugin page. See [Rendering model](https://docs.qomicex.top/en/plugins/pitfalls.md).
* Project-based plugins use the `@qomicex/plugin-ui` React components plus Tailwind; see [React + Vite plugin development](https://docs.qomicex.top/en/plugins/react-plugin.md).

## 3. Package the plugin

### Package with the CLI (recommended)

```bash theme={null}
qomicex pack                # tsc && vite build → release/<id>-<version>.qplugin
qomicex pack --key ./dev-key.pem    # attach a signature (verifiable offline)
```

A `.qplugin` file is a zip with `manifest.json` at the root plus `dist/**`. If `entry.theme` or `contributes.overlay.file` reference files under `dist/` while the source sits in the root directory, `pack` copies them in automatically.

`manifest.json` must be in the **root directory** of the archive. Putting it in a subdirectory makes installation fail.

### Manual packaging without the CLI (alternative)

* Put `manifest.json` and the asset directory into one folder
* Compress it with any ZIP tool, making sure `manifest.json` is at the **ZIP root**
* Rename the extension to `.qplugin`

```text theme={null}
my-plugin.qplugin          # i.e. a zip with manifest.json at the root
```

## 4. Install and test

* Open Qomicex Launcher → Settings → Plugins
* Click **Install plugin (Install plugin)** and select your `.qplugin` file
* After a successful install, the card appears in the plugin list; toggle it on to enable it (a launcher restart is required for it to take effect)
* After the restart, a "Hello" entry appears in the sidebar; click it to open the plugin page

During development, run `qomicex dev` to use the debug harness (no Tauri/backend needed, hot reload in the browser). See [Debugging and hot reload](https://docs.qomicex.top/en/plugins/debugging.md).

## 5. FAQ at a glance

| Symptom | Cause |
| - | - |
| Installation fails with `Invalid plugin package` | `manifest.json` is not at the package root, or JSON parsing failed |
| The plugin appears in the list but there is no sidebar entry | `contributes.menuItems` is not declared, or the plugin is not enabled |
| Blank page / script does not run | The plugin is not activated, or there is an activation timing problem (see [Pitfalls guide](https://docs.qomicex.top/en/plugins/pitfalls.md)) |
| An API call fails with `Permission denied` | `permissions` in the manifest does not include the required permission |
| `qomicex pack` reports an error | Run `qomicex verify` / `qomicex lint` first to locate the problem |

## Next steps

* Learn every manifest field: [Manifest reference](https://docs.qomicex.top/en/plugins/manifest.md)
* Learn every callable API: [Complete plugin API reference](https://docs.qomicex.top/en/plugins/plugin-api.md)
* Project-based development: [React + Vite plugin development](https://docs.qomicex.top/en/plugins/react-plugin.md)
* Full CLI commands: [CLI reference](https://docs.qomicex.top/en/plugins/cli.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.