The manifest

// plugins/dev/manifest.ts
import { definePlugin, PLUGIN_API_VERSION } from '@desk/shared';

export default definePlugin({
  id: 'dev', // lower case letters and digits; the folder name, and the prefix of routes and tables
  name: 'Software Development',
  description: 'A kanban board of developer tasks per organization, linked to cases …',
  version: '1.0.0',
  scopes: [
    { name: 'dev:read', label: 'Read dev projects', hint: 'Projects you can use, their boards, tasks …' },
    { name: 'dev:write', label: 'Change dev tasks', hint: 'Create, edit and move dev tasks …' },
  ],
  // Events for webhooks (and other plugins): `<id>.<what>` → what it means.
  events: { 'dev.task.created': 'A dev task was created', 'dev.task.done': 'A dev task entered a done column' },
  // The kinds of email it sends staff; each person can turn one off (Settings → Notifications).
  notifications: { task: { label: 'Tasks you watch', description: 'Comments and mentions on dev tasks you watch, and when they are done.' } },
  // The extension point version it was built for, and plugins that must be on first (by id).
  requires: { desk: PLUGIN_API_VERSION, plugins: [] },
});

What the desk checks

[!WARNING] The desk refuses to start with a manifest that is wrong.

It refuses:

• an id that doesn't match the folder;
• scopes that don't start with <id>:, or events that don't start with <id>.;
• permission and role keys that don't start with the plugin's permission prefix: its id, or permissionPrefix (one word that isn't a desk area, like incident, or, for a plugin that extends one it requires, under that one's prefix, like incident.major; two plugins never share one);
• a requires.desk other than the desk's PLUGIN_API_VERSION (raised when the extension points change in a way plugins notice; it is 3 since the case hooks, slots and types got their current names);
• requires.plugins naming a plugin that isn't in plugins.config.ts, or plugins that need each other in a circle.

Required plugins

Plugins are layers: a plugin that needs another (requires.plugins) is built on it, like Incident Management on Service Configuration (itsm). It is only on while everything it needs is on.

When	What happens
It is turned on	What it needs is turned on too (each audited, with neededBy).
What it needs is turned off	Its own switch stays as it was, so it is off until that is on again and then comes back by itself. The plugin.disabled entry lists what went off with it in alsoOff.

[!TIP] Build an IT plugin on itsm (or on a plugin built on it), so a support desk without IT can leave it out in one switch.

Help pages

A page in docs/ about one plugin starts with <!-- plugin: <id> -->. Help leaves it, and the list items in the section indexes that link to it, out while the plugin is off.

No licence checks in plugins

[!IMPORTANT] Every plugin is free. The desk's own licence key says which plugins may be turned on (the free key allows every plugin), and the desk checks that when a plugin is turned on. A plugin never adds a licence or entitlement check of its own.