Build plugins for XLibrary

What a plugin can add

• Game catalogs and browser sources
• Import and export formats
• Library filters
• Custom game fields and actions
• Focused UI tools
• Background integrations

Create a runnable starter

You need Node.js 20 or newer and pnpm 10 or newer. npm works as well: npx @xlibrary/plugin-sdk create .

The generator creates manifest.json, src/index.ts, a contract test, tsconfig.json and the build, demo and package scripts. pnpm demo runs the compiled plugin through the SDK test host and prints a sample search and resolve result without opening XLibrary or making a real network request. pnpm package creates dist/<plugin-id>-<version>.xlplugin.

mkdir my-xlibrary-plugin
cd my-xlibrary-plugin
pnpm dlx @xlibrary/plugin-sdk create .
pnpm install
pnpm test
pnpm demo
pnpm package

Isolation and permissions

Plugins are opt-in. XLibrary validates a .xlplugin package before installation, asks you to approve its permissions and runs its entry module in an isolated runtime.

Each plugin has its own settings, connected accounts and diagnostics, with safe enable, disable, retry and uninstall controls. Backups include plugin data.

Test without XLibrary

The SDK test host records calls, controls time and validates result shapes, so you can test a provider without starting the app. When a plugin returns an invalid result, the test helpers throw PluginContractValidationError with the exact field path, a stable error code, a message and, where useful, a correction hint.

Install a plugin

1. Build the package with pnpm package.
2. In XLibrary, open Plugins and choose Install plugin.
3. Review and approve the permissions it asks for.

There is no public plugin catalog yet

Share .xlplugin files on Discord.