SDK Overview
The Plenary JavaScript SDK is six npm packages, versioned together (currently 1.0.x; see the changelog). You can build a site on plain HTTP alone (see Without the SDK); the SDK gives you typed reads, typed errors, the Page Builder renderer, and Next.js or Nuxt cache revalidation.
The packages
Section titled “The packages”| Package | What it is for | Depends on |
|---|---|---|
@plenary/client |
Framework-free API client: content reads, GraphQL queries, form definitions and submissions, media lookup, and webhook verification helpers. Works anywhere fetch does. |
@plenary/core |
@plenary/react |
Renders Page Builder documents with React, registers your own components, and hosts the live preview bridge. | @plenary/core, @plenary/client; peer react and react-dom 18 or 19 |
@plenary/next |
Next.js glue: route handlers that turn Plenary webhooks into revalidatePath/revalidateTag calls, and a fetch wrapper that tags content reads. |
@plenary/client; peer next 14, 15, or 16 |
@plenary/nuxt |
Nuxt glue: a module and a server handler that turn Plenary webhooks into purges of Nitro’s response cache. | @plenary/client, @nuxt/kit, h3; runs in Nuxt 4 |
@plenary/core |
Shared types and small runtime helpers: the Page Builder document model, component registration types, the preview protocol. Zero dependencies. You rarely import it directly except for types. | None |
@plenary/cli |
The plenary command: sync model definitions as YAML, automate content, run GraphQL queries, and call any API endpoint. See CLI. |
@plenary/client |
Choose what to install
Section titled “Choose what to install”| You are building | Install |
|---|---|
| Any JavaScript or TypeScript app that reads content or submits forms | @plenary/client |
| A Next.js site with structured content (blog, docs, listings) | @plenary/client @plenary/next |
| A Nuxt site with structured content | @plenary/client @plenary/nuxt |
| A React or Next.js site whose pages are built in the Page Builder | @plenary/client @plenary/react (plus @plenary/next on Next.js) |
| Something in another language | Nothing; use the Content API directly |
| Model definitions kept in your repository | @plenary/cli as a dev dependency |
# Structured content on Next.jsnpm install @plenary/client @plenary/next
# Page Builder pages on Next.jsnpm install @plenary/client @plenary/react @plenary/next
# Structured content on Nuxtnpm install @plenary/client @plenary/nuxt
# Command-line tool, per projectnpm install --save-dev @plenary/cliKeep every @plenary/* package on the same version. They are released together and share types, and mixing versions can leave two copies of the error classes, which breaks instanceof checks.
Compatibility
Section titled “Compatibility”| Requirement | Supported |
|---|---|
| Node.js | 20 or later. @plenary/cli requires Node 20; Next.js 16 itself requires 20.9. |
| React | 18 or 19 (@plenary/react peer dependency) |
| Next.js | 14, 15, or 16 (@plenary/next peer dependency). The Pages Router handler is at @plenary/next/pages. |
| Nuxt | 4 (@plenary/nuxt module compatibility check), on Nitro 2 and h3 1. |
| Module format | @plenary/client, @plenary/next, and @plenary/core ship ESM and CommonJS. @plenary/react, @plenary/nuxt, and @plenary/cli are ESM only. |
| TypeScript | Type declarations are included in every package. |
| Runtimes | @plenary/client uses the global fetch, so it runs in Node, browsers, and edge runtimes. You can pass your own fetch. |
Configuration
Section titled “Configuration”Every SDK entry point starts from a client created with four required values. Keep them in environment variables:
| Environment variable | Client option | Example | Meaning |
|---|---|---|---|
PLENARY_BASE_URL |
baseUrl |
https://your-instance.plenarycms.io |
Your instance’s origin, without /api/v1. |
PLENARY_API_KEY |
apiKey |
pln_pub_… |
An API key, sent as the X-API-KEY header. |
PLENARY_SITE_KEY |
siteKey |
default |
The site to read from, sent as site_key on every request. |
PLENARY_LOCALE |
locale |
en-us |
The default locale, sent as locale on every read. |
PLENARY_BASE_URL=https://your-instance.plenarycms.ioPLENARY_API_KEY=pln_pub_your_public_keyPLENARY_SITE_KEY=defaultPLENARY_LOCALE=en-usimport { createClient } from "@plenary/client";
export const plenary = createClient({ baseUrl: process.env.PLENARY_BASE_URL!, apiKey: process.env.PLENARY_API_KEY!, siteKey: process.env.PLENARY_SITE_KEY ?? "default", locale: process.env.PLENARY_LOCALE ?? "en-us",});Where to find the values:
- Base URL: the address of your instance. The console is served at
/cmson the same origin, so if you sign in athttps://your-instance.plenarycms.io/cms, the base URL ishttps://your-instance.plenarycms.io. - API key: create one under Access Management → API Keys. Use a public key for rendering content. See Authentication.
- Site key: shown under Admin Settings → Site Management. A new instance has one site, usually
default. - Locale: one of the site’s locales, lowercase (
en-us,fr-ca). See Localization.
The client always sends site_key and locale, so reads never depend on server-side fallbacks. Override either per call with the siteKey and locale options.
Related
Section titled “Related”- Quickstart: from a new instance to content on a page.
- Blog with Next.js: a complete example using
@plenary/client. - Instant revalidation:
@plenary/nextand webhooks end to end. - Building with AI agents: giving a coding agent what it needs.