XLibrary Plugin SDK

Templates, a CLI, typed contracts and deterministic test tools for XLibrary .xlplugin packages.

Create a plugin

npx @xlibrary/plugin-sdk create my-plugin --template game-source
cd my-plugin
npm install
npm test
npm run check
npm run package

The JavaScript templates have no build step: the plugin is runtime/index.js, loaded by XLibrary as it is. Node.js 20+ is needed only for the tests and the CLI. Install the resulting dist/<id>-<version>.xlplugin in XLibrary → Plugins.

| Template | What it adds | | --- | --- | | game-source | A provider in "+ Add game": search a site over HTTPS, add a game | | download-source | A download source: torrents for a game with a tracker sign-in | | game-action | Game page buttons that change tags and status, and a sidebar panel | | widget | A panel with library numbers on the Library page | | starter | The TypeScript starter with a local preview (pnpm build first) |

Working with an AI agent? XLibrary 3.11+ is an MCP server: turn on Plugin development in AI Agents and ask the agent to create a plugin. See docs/agent-workflow.md.

CLI

xlibrary-plugin create [directory] [--template name] [--id id] [--name text] [--author text] [--install]
xlibrary-plugin check [directory] [--json]
xlibrary-plugin pack [directory] [--out file]
xlibrary-plugin preview [directory] [--query text]

• create copies a template and fills in the id, name, author and SDK version.
• check validates the manifest with the XLibrary rules, the package contents, and the rules of the XLibrary catalog server, including the script rules that flag a published version. --json prints a machine-readable report.
• pack runs the same checks, then writes an archive with manifest.json, runtime/, locales/, LICENSE and README.
• preview runs a game-source plugin through the test host.

Documentation

Start with docs/overview.md. The most used pages:

• docs/agent-workflow.md — from an idea to a working plugin, with or without the XLibrary MCP tools;
• docs/manifest.md and docs/permissions.md — what to declare;
• docs/runtime-api.md, docs/contributions.md, docs/ui-slots.md — what to implement;
• docs/testing.md — tests without XLibrary;
• docs/validation-rules.md and docs/publishing.md — getting into the catalog.

Live examples: the official plugins rpdl and thread-mirrors.

Test without XLibrary

import {createPluginTestHost, runGameSourceSearch} from '@xlibrary/plugin-sdk/testing';
import plugin from '../runtime/index.js';

const host = createPluginTestHost({
  permissions: ['game-sources.providers', 'network.http'],
  network: ({url}) => ({status: 200, body: btoa(JSON.stringify({results: []}))}),
});
const result = await runGameSourceSearch(plugin, {sourceId: 'catalog', query: 'example', limit: 20}, host);

The test host records calls, controls time, denies host calls without a declared permission, and validates results. Invalid results throw PluginContractValidationError with the exact field path, a stable code, and a hint.

Types

npm install -D @xlibrary/plugin-sdk

In JavaScript, use JSDoc: /** @type {import('@xlibrary/plugin-sdk').XLibraryPlugin} */. In TypeScript, import type {XLibraryPlugin} from '@xlibrary/plugin-sdk'. The SDK is a development dependency only: a packaged plugin never imports it at runtime.