SDKs | Plotwork docs

SDKs

How to show Plotwork diagrams in your own pages and apps, import .diagram files into a Vite build, and call the Plotwork API from code. The packages are published on npm under @plotwork.official (opens in a new tab), and the Python client on PyPI as plotwork (opens in a new tab). It is for developers who build Plotwork into a product, a portal or a script.

TL;DR

Question	Answer
Which packages are there?	`@plotwork.official/viewer` shows a diagram, `@plotwork.official/vite` imports `.diagram` files, `@plotwork.official/sdk` calls the API from JavaScript, and `plotwork` calls it from Python.
What do they install?	Nothing else. Each has no runtime dependencies; React and Vite are optional peers, and the Python client uses the standard library only.
How are they published?	From CI by trusted publishing on npm and PyPI, with a signed provenance statement and no stored token. `npm audit signatures` checks an npm package after you install it.
Is there a Python client?	Yes: `pip install plotwork`, for Python 3.10 and later, fully typed.
Can my app's people sign in with Plotwork?	Yes. `@plotwork.official/sdk/oauth` and `plotwork.oauth` run the sign-in, and the viewer shows each person's private diagrams with their token. See Sign in with Plotwork.
Where is the source?	`plotwork-official/plotwork-sdk` (opens in a new tab), MIT licence.

Packages

Package	Registry	What it is
`@plotwork.official/viewer`	npm (opens in a new tab)	`<plotwork-diagram>` for any page and `<PlotworkDiagram>` for React: pan and zoom, tracing a box's lines, drilling into a part, light and dark, and live updates.
`@plotwork.official/vite`	npm (opens in a new tab)	Imports a `.diagram` file as the SVG the command line draws at build time, redrawn on save. No engine reaches the browser.
`@plotwork.official/sdk`	npm (opens in a new tab)	Every public `/v1` operation as a typed call, with the types of the API's OpenAPI document, sent with `fetch` alone.
`plotwork`	PyPI (opens in a new tab)	The same API client for Python, typed, on the standard library only.

Show a diagram

npm install @plotwork.official/viewer

1<script type="module">2  import '@plotwork.official/viewer/register'3</script>4
5<plotwork-diagram src="https://cdn.plotwork.dev/l/q3Zr8J1x0bWcVvKm2hT9pA.svg" label="Checkout flow" live></plotwork-diagram>

Point src at a stable link with live to follow each new version, an SVG your site serves, or an organisation embed link. plotwork embed and the embed_diagram tool write this snippet for you. The viewer's page on npm (opens in a new tab) lists every attribute, event and style hook.

Import a `.diagram` file

npm install --save-dev @plotwork.official/vite @buun_group/plotwork

1// vite.config.ts2import { defineConfig } from 'vite'3import { plotwork } from '@plotwork.official/vite'4
5export default defineConfig({ plugins: [plotwork()] })

1import checkout from './diagrams/checkout.diagram'2import { PlotworkDiagram } from '@plotwork.official/viewer/react'3
4export const Checkout = () => <PlotworkDiagram svg={checkout} label="Checkout flow" />

A mistake in a diagram stops the build with the command line's line, column and hint in Vite's overlay.

Call the API

npm install @plotwork.official/sdk

1import { Plotwork } from '@plotwork.official/sdk'2
3const plotwork = new Plotwork({ apiKey: process.env.PLOTWORK_API_KEY })4const checked = await plotwork.diagrams.validate({ source })

From Python:

pip install plotwork

1import os2from plotwork import Plotwork3
4plotwork = Plotwork(api_key=os.environ["PLOTWORK_API_KEY"])5checked = plotwork.diagrams.validate(source=source)

Make a key in the portal (opens in a new tab) and keep it in an environment variable or your CI's secret store. A mistake in a diagram is part of the answer; only a failed request throws or raises, as PlotworkApiError with a stable error code. The API reference describes each operation.

Sign people in with Plotwork

An app whose people have Plotwork accounts calls the API as each person, with no API key, through Sign in with Plotwork. The helpers are in @plotwork.official/sdk/oauth (createPkce, authorizeUrl, parseRedirect, exchangeCode, refreshToken, revokeToken, withRefresh) and in Python's plotwork.oauth.

1import { Plotwork } from '@plotwork.official/sdk'2import { withRefresh } from '@plotwork.official/sdk/oauth'3import { PlotworkLibrary } from '@plotwork.official/viewer/react'4
5const token = withRefresh(tokens, { clientId, onRefresh: save })6const plotwork = new Plotwork({ accessToken: token })7
8<PlotworkLibrary token={token} onSelect={({ pictureUrl }) => show(pictureUrl)} />

The viewer's token shows a private picture of the person's library, and <plotwork-library> lets them pick one. An API key stays on a server; a person's token is fine in a browser.

Page	Why
Hosted diagrams	Stable links, embed links and live updates
`plotwork embed`	Writes a viewer snippet for a file or a link
API reference	Every operation the SDK calls
Sign in with Plotwork	Let your app's people sign in and call the API as themselves
Why Plotwork draws plain SVG	What a picture adds to your page