deck-plugin-sdk

Build a plugin for Deck, outside Deck's own repository.

npm create deck-plugin my-thing
cd my-thing
npm run dev            # rebuild as you edit; each save shows in your test Deck
npm run install-local  # when it is done: install it into your real Deck

Develop in a test Deck: a second Deck beside yours, with its own settings and data, started from Settings › Plugins › Open a test Deck (or deck.exe --test). npm run dev installs into it after every build and it reloads the plugin, so a save shows there within a few seconds, while your real Deck and its data are never touched.

The project comes with an AGENTS.md (and a CLAUDE.md that points to it), so Claude Code, Codex or another agent started in the folder knows the commands, the API and the rules.

What a plugin is

A folder with a plugin.json and a built plugin.js, read from %APPDATA%\Deck\plugins\<id>\ when Deck starts. It becomes a tab, or a readout in the footer, or a panel, or commands in the palette — docs/guide/api.md in the Deck repository lists every slot a plugin can fill. One is enough.

Your sources import react, lucide-react and deck-plugin-sdk/* as ordinary code does. At run time those resolve to Deck's copies, handed over on window.__deck. For React that is not an optimisation but a requirement: two Reacts in one tree break hooks.

Commands

| | | |---|---| | deck-plugin build | bundle src/ into plugin.js | | deck-plugin dev | rebuild whenever a source changes, and install each build into the test Deck | | deck-plugin check | validate plugin.json without building | | deck-plugin install | build once, then install into your real Deck | | deck-plugin publish | check everything Deck's registry checks, then tag, release on GitHub and submit it (--dry-run: only check); see Publishing |

--target test or --target main picks the other Deck for either command. The test Deck keeps its plugins in %APPDATA%\Deck-Dev\plugins, your real Deck in %APPDATA%\Deck\plugins.

What you can import

import { configRead, configWrite } from "deck-plugin-sdk/bridge";  // Deck's Tauri commands
import { listen } from "deck-plugin-sdk/event";                     // Deck's event bus
import { getSettings } from "deck-plugin-sdk/settings";             // Deck's settings store
import { Field, GhostButton } from "deck-plugin-sdk/ui";            // Deck's form controls
import { getLayout } from "deck-plugin-sdk/terminals";              // the terminal layout
import { monaco } from "deck-plugin-sdk/monaco";                    // the editor

They come from the package, so the project holds only your own code. A plugin made with an older SDK imports ../shim/bridge.js instead; the build still copies shim/ and types/ in for one of those, and switching its imports over makes both unnecessary.

The types are generated from Deck's own source, so what your editor tells you is what Deck actually exposes rather than a hand-written approximation that has drifted.

Any other npm package is npm install and import: the build bundles it into plugin.js, with the images, fonts and CSS it brings. Writing a plugin, in the Docs, says what cannot work that way.

Two things a build often needs are settings, which the registry can still rebuild:

• A worker of your own: import code from "./job.worker.ts?worker" bundles that file and what it imports into one script and gives its text, to start with new Worker(URL.createObjectURL(new Blob([code]))).

• Files a package brings that you never use (a library's translations into every language): regular expressions in package.json, matched against each file's path, and each match is bundled empty:

  "deckPlugin": { "leaveOut": ["/locales/(?!en-)[^/]+\\.js$"] }

When the build needs more than that, export esbuild plugins from deck-plugin.config.mjs beside plugin.json. The registry does not run your code, so it cannot rebuild a plugin that has one: it is listed as build not verified, and misses those points.

export const esbuildPlugins = [{ name: "my-step", setup(build) { /* ... */ } }];

What a plugin cannot do

Add native capability. Every Tauri command is compiled into Deck, so a plugin calls what already exists. Anything needing new Rust belongs in Deck itself.

What a plugin CAN do, which is worth saying plainly

Everything Deck can. A plugin runs inside Deck with the whole bridge: every Tauri command, the config directory, the filesystem, the terminal, a Google access token if one is connected. There is no sandbox and no permission prompt.

That is a deliberate position rather than an oversight — a plugin is code you chose to run, like a VS Code extension or a shell script. It is also why the plugin registry is curated rather than open: an entry exists there because it was reviewed, and installing a plugin from anywhere else is the same decision as running any other program.

Versions

The SDK's major and minor track Deck's, so an SDK 0.15 builds plugins for Deck 0.15. Declare the oldest Deck you work with as minDeck in plugin.json; Deck refuses to load a plugin that needs a newer one, with a sentence rather than an error from inside your module.

Publishing

A plugin is published by being listed in Deck's registry, which points at a release in your own repository. deck-plugin publish makes the release and submits it; deck-plugin publish --dry-run runs every check the registry will and prints the points the version will get, check by check. Everything else is in Publishing.