# SDKs

> Page: https://docs.plotwork.dev/sdks. Index of every page: https://docs.plotwork.dev/llms.txt

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`](https://www.npmjs.com/org/plotwork.official), and the Python client on PyPI as [`plotwork`](https://pypi.org/project/plotwork/). 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](https://docs.plotwork.dev/sign-in-with-plotwork.md). |
| Where is the source? | [`plotwork-official/plotwork-sdk`](https://github.com/plotwork-official/plotwork-sdk), MIT licence. |

## Packages

| Package | Registry | What it is |
|---|---|---|
| `@plotwork.official/viewer` | [npm](https://www.npmjs.com/package/@plotwork.official/viewer) | `<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](https://www.npmjs.com/package/@plotwork.official/vite) | 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](https://www.npmjs.com/package/@plotwork.official/sdk) | Every public `/v1` operation as a typed call, with the types of the API's OpenAPI document, sent with `fetch` alone. |
| `plotwork` | [PyPI](https://pypi.org/project/plotwork/) | The same API client for Python, typed, on the standard library only. |

## Show a diagram

```shell
npm install @plotwork.official/viewer
```

```html
<script type="module">
  import '@plotwork.official/viewer/register'
</script>

<plotwork-diagram src="https://cdn.plotwork.dev/l/q3Zr8J1x0bWcVvKm2hT9pA.svg" label="Checkout flow" live></plotwork-diagram>
```

Point `src` at a [stable link](https://docs.plotwork.dev/hosted-diagrams.md) with `live` to follow each new version, an SVG your site serves, or an organisation embed link. [`plotwork embed`](https://docs.plotwork.dev/cli/commands/embed.md) and the `embed_diagram` tool write this snippet for you. The [viewer's page on npm](https://www.npmjs.com/package/@plotwork.official/viewer) lists every attribute, event and style hook.

## Import a `.diagram` file

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

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { plotwork } from '@plotwork.official/vite'

export default defineConfig({ plugins: [plotwork()] })
```

```tsx
import checkout from './diagrams/checkout.diagram'
import { PlotworkDiagram } from '@plotwork.official/viewer/react'

export 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

```shell
npm install @plotwork.official/sdk
```

```ts
import { Plotwork } from '@plotwork.official/sdk'

const plotwork = new Plotwork({ apiKey: process.env.PLOTWORK_API_KEY })
const checked = await plotwork.diagrams.validate({ source })
```

From Python:

```shell
pip install plotwork
```

```python
import os
from plotwork import Plotwork

plotwork = Plotwork(api_key=os.environ["PLOTWORK_API_KEY"])
checked = plotwork.diagrams.validate(source=source)
```

Make a key in the [portal](https://app.plotwork.dev) 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](https://docs.plotwork.dev/api/reference.md) 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](https://docs.plotwork.dev/sign-in-with-plotwork.md). The helpers are in `@plotwork.official/sdk/oauth` (`createPkce`, `authorizeUrl`, `parseRedirect`, `exchangeCode`, `refreshToken`, `revokeToken`, `withRefresh`) and in Python's `plotwork.oauth`.

```ts
import { Plotwork } from '@plotwork.official/sdk'
import { withRefresh } from '@plotwork.official/sdk/oauth'
import { PlotworkLibrary } from '@plotwork.official/viewer/react'

const token = withRefresh(tokens, { clientId, onRefresh: save })
const plotwork = new Plotwork({ accessToken: token })

<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.

## See also

| Page | Why |
|---|---|
| [Hosted diagrams](https://docs.plotwork.dev/hosted-diagrams.md) | Stable links, embed links and live updates |
| [`plotwork embed`](https://docs.plotwork.dev/cli/commands/embed.md) | Writes a viewer snippet for a file or a link |
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every operation the SDK calls |
| [Sign in with Plotwork](https://docs.plotwork.dev/sign-in-with-plotwork.md) | Let your app's people sign in and call the API as themselves |
| [Why Plotwork draws plain SVG](https://docs.plotwork.dev/why-svg.md) | What a picture adds to your page |