NextPress documentation

SDK

Open as markdown

Use the TypeScript SDK to create, update and publish pages, read content, share preview links, and handle errors.

On this page

The SDK, @nextpress-org/sdk, is a TypeScript library for working with one NextPress site from your own code. It needs Node.js 20 or later and an API key.

1. Install it

Shell
pnpm add @nextpress-org/sdk

With npm, run npm install @nextpress-org/sdk.

2. Create a client

Pass the site's address, the key, and the site ID shown with the key when you created it. The site ID is a UUID.

TypeScript
import { createNextpress } from "@nextpress-org/sdk";

const apiKey = process.env.NEXTPRESS_API_KEY;
if (!apiKey) throw new Error("Set NEXTPRESS_API_KEY");

export const nextpress = createNextpress({
  baseUrl: "https://cms.example.com",
  apiKey,
  siteId: "3f2b9c1e-8a4d-4c7b-9e21-5d6f7a8b9c0d",
});
OptionRequiredDefaultWhat it does
baseUrlYesNoneThe site's address
apiKeyYesNoneThe key, starting with npk_live_
siteIdYesNoneThe UUID of the key's site
timeoutNo30000Milliseconds to wait for an answer
fetchNoThe built-in fetchA custom fetch, for proxies or tests

nextpress.config exposes baseUrl and siteId, never the key.

3. Create a page

Calls that change content return a result instead of throwing. Check isErr before you use value.

TypeScript
const created = await nextpress.pages.create({
  title: "About us",
  status: "draft",
  blocks: [
    nextpress.blocks.heading({ text: "About us", level: 1 }),
    nextpress.blocks.paragraph({ text: "We build websites for local shops." }),
  ],
});

if (created.isErr) {
  console.error(created.error.code, created.error.message);
} else {
  console.log("Created page", created.value.id);
}

4. Update and publish it

An update must carry expectedVersion, the page version you last read. If someone saved the page since, the update fails with the code VERSION_STALE. Read the page again and retry.

TypeScript
const page = await nextpress.pages.get({ id: "8d1c2b3a-4e5f-4a6b-9c7d-0e1f2a3b4c5d" });

const published = await nextpress.pages.update({
  id: page.id,
  expectedVersion: page.version ?? 0,
  status: "publish",
  publishedAt: new Date().toISOString(),
});

if (published.isErr) throw published.error;

5. Read content

Reads return the data and throw a NextpressError when the request fails.

TypeScript
const { posts, total } = await nextpress.posts.list({ status: "publish", per_page: 10 });

const homepage = await nextpress.public.homepage();
const about = await nextpress.public.page({ slug: "about" });

per_page can be at most 100. nextpress.public reads published content and sends no key.

A preview link shows a draft without signing in. The key needs preview:write and read access to the content.

TypeScript
const share = await nextpress.preview.createShareToken({
  contentType: "page",
  contentId: page.id,
  expiresInSeconds: 600,
});

console.log(share.previewUrl, share.expiresAt);

contentType is page, post or template. Without expiresInSeconds, the link lasts 300 seconds. The most is 3600.

Handle errors

TypeScript
import { isNextpressError } from "@nextpress-org/sdk";

const result = await nextpress.pages.create({ title: "Draft", blocks: [] });
if (result.isErr && result.error.code === "API_KEY_SCOPE_DENIED") {
  console.error("This key needs more permissions. Edit them in Settings, System, API Keys.");
}

try {
  await nextpress.pages.list({ per_page: 20 });
} catch (error) {
  if (isNextpressError(error)) console.error(error.status, error.code, error.message);
}

A NextpressError has status, code and message. Invalid input, such as a siteId that is not a UUID, throws before any request is sent.

Blocks

nextpress.blocks builds blocks with the same defaults as the editor, through helpers such as heading, paragraph, image, button, columns, form and postList. For a block without a helper, use fromName, such as nextpress.blocks.fromName("core/card"). The list is in the Block reference.

Editing with undo

nextpress.createEditorSession() keeps a working copy of a page or post with undo, redo, save, publish and createPreviewLink. Most scripts need only create and update.

Next steps