Skip to content

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.

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
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
Terminal window
# Structured content on Next.js
npm install @plenary/client @plenary/next
# Page Builder pages on Next.js
npm install @plenary/client @plenary/react @plenary/next
# Structured content on Nuxt
npm install @plenary/client @plenary/nuxt
# Command-line tool, per project
npm install --save-dev @plenary/cli

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

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.

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.
.env.local
PLENARY_BASE_URL=https://your-instance.plenarycms.io
PLENARY_API_KEY=pln_pub_your_public_key
PLENARY_SITE_KEY=default
PLENARY_LOCALE=en-us
lib/plenary.ts
import { 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 /cms on the same origin, so if you sign in at https://your-instance.plenarycms.io/cms, the base URL is https://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.