Plugin SDKs
This folder holds one guide per SDK language, each followed by the reference generated from that SDK's code. Pick the language you write in; the plugin model is the same in all three, and Dynamic plugins explains it.
| Language | Package | Runs as | Guide |
|---|---|---|---|
| TypeScript | @bookclerk/plugin-sdk |
A workerd isolate | TypeScript plugin SDK |
| Python | bookclerk-plugin-sdk |
A workerd isolate (Python Workers) | Python plugin SDK |
| Rust | bookclerk-plugin-sdk |
A native binary, or a workerd isolate through Wasm | Rust plugin SDK |
Third-party plugins depend on the SDK only, never on
bookclerk-plugin-host, bookclerk-library or bookclerk-source.
First-party native storefront guests add their private store crates and
bookclerk-storefront, the slim crate of storefront types they share with
the host (the Audible guest also links bookclerk-audible-catalog and
bookclerk-mp4, and the Libro.fm, Chirp and GraphicAudio guests link
bookclerk-scan-delta for their scan deltas). It has no database, ORM, configuration or OpenAPI dependencies,
so a guest build stays small.
plugin.toml names one of two runtimes:
runtime |
How it runs |
|---|---|
workerd |
Author modules/ loaded by bookclerk-workerd: one jail and one isolate per plugin (a local embed, not Cloudflare cloud execution) |
native |
An OS binary speaking the same Workers RPC ABI. The host starts two sibling jails, bookclerk-workerd (control plane) and the native backend, joined by inherited duplex links |
TypeScript and Python plugins are workerd plugins. Rust plugins are
native, or workerd when compiled to Wasm with the SDK's workerd glue.
- The entrypoint base classes:
BookclerkEntrypointfor the default export, and one*Entrypointbase per named entrypoint (Storefront,Storage,RemoteLibrary,DatabaseAdapter,Cli,Oidc,Metadata,Covers). - The ABI types, generated from
plugin.capnpso all three SDKs speak the same wire. - An author CLI:
checkvalidates the package against the author model,typeswrites anEnvtype fromplugin.toml,fmtformats the manifest,packagebuilds the archive, andsmokeruns a workerd plugin against the pinnedworkerdwithout a built host.
- plugin.toml: the manifest every plugin starts with.
- Entrypoints, events and the ABI: the methods each entrypoint implements.
- Dynamic plugins: run a plugin against a local host.
Source: docs/plugins/sdk/README.md at main · View as Markdown