Next.js SDK

The SDK renders published RootSmith pages in your Next.js app, adds them to your sitemap, and receives a signed refresh when you publish.

RequirementsCopy Anchor Link

• Next.js 15 or 16 with the App Router, and React 19.
• A server runtime. For output: "export", use static sites instead.
• The site deployed at the primary domain saved for the site in RootSmith, over HTTPS.

1. Install the packageCopy Anchor Link

npm install @rootsmithio/next

2. Add environment variablesCopy Anchor Link

Open Sites → Publishing → Set up SDK in RootSmith to copy these values. An agent can get the first two from the get_sdk_setup tool.

ROOTSMITH_API_URL=https://api.example.com
ROOTSMITH_SITE_ID=00000000-0000-0000-0000-000000000000
ROOTSMITH_CONNECTION_SECRET=

Add the same three variables to your host, such as Vercel, for production.

3. Create the clientCopy Anchor Link

import { createRootSmith } from "@rootsmithio/next"

export const rootSmith = createRootSmith({
  apiUrl: process.env.ROOTSMITH_API_URL!,
  siteId: process.env.ROOTSMITH_SITE_ID!,
})

4. Render pagesCopy Anchor Link

Add a catch-all route that asks RootSmith for the requested path:

import "@rootsmithio/next/styles.css"
import { notFound } from "next/navigation"
import { pageMetadata } from "@rootsmithio/next"
import { RootSmithPage } from "@rootsmithio/next/markdown"
import { rootSmith } from "@/lib/rootsmith"

type Props = { params: Promise<{ path: string[] }> }

export async function generateStaticParams() {
  return []
}

async function get(params: Props["params"]) {
  const { path } = await params
  const page = await rootSmith.getPage(`/${path.join("/")}`)
  if (!page) notFound()
  return page
}

export async function generateMetadata({ params }: Props) {
  return pageMetadata(await get(params))
}

export default async function Page({ params }: Props) {
  return <RootSmithPage page={await get(params)} />
}

The empty generateStaticParams renders each page on its first visit, then serves it from the Next.js cache.

Adapt the paths to the project:

• With a src folder, use src/app/... and src/lib/....
• Without the @/ import alias, use a relative import.
• If the app already has a root catch-all route, add one route for each page type's URL prefix instead, such as app/blog/[...path]/page.tsx. Pass the full path to getPage, such as `/blog/${path.join("/")}`.
• Wrap RootSmithPage in your site's layout or article shell as needed.

5. Add the refresh handlerCopy Anchor Link

import { createRootSmithHandler } from "@rootsmithio/next"

export const POST = createRootSmithHandler()

RootSmith calls this route to verify the connection and to refresh a page after you publish. It must be public. If your app uses auth middleware, a proxy.ts or middleware.ts matcher, basic auth, or deployment protection, let POST /api/rootsmith through. The handler checks its own signature.

6. List pages in your sitemapCopy Anchor Link

import type { MetadataRoute } from "next"
import { rootSmith } from "@/lib/rootsmith"

export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
  const pages = await rootSmith.listAllPages()
  return pages.map((page) => ({ url: page.url, lastModified: page.updatedAt }))
}

If the site already has a sitemap, add these entries to it.

7. Deploy and connectCopy Anchor Link

1. Deploy the site with the three environment variables set.
2. In Publishing, enter /api/rootsmith as the Delivery endpoint and select Save and verify.
3. The status changes to Connected.

An agent does step 2 with update_publishing_settings, then verify_publishing_connection. See Install with an agent.

How refresh and caching workCopy Anchor Link

• SDK reads use the Next.js data cache with the rootsmith tag for one hour. During next build, they last one second, so each build reads current content.
• When you publish, RootSmith sends a signed refresh. The handler expires the rootsmith tag, so the next request renders the new version.
• If a refresh is lost, the page corrects itself within an hour.
• If the refresh fails, RootSmith restores the previous version and tells you.
• When a page is merged into another, getPage sends a permanent (308) redirect to the page that replaced it.
• getPage returns null for an unknown path and for paths that can't be content, such as /favicon.ico or a path with a trailing slash.

CustomizeCopy Anchor Link

• Styles: @rootsmithio/next/styles.css matches the RootSmith preview. Override its rootsmith-* classes, or leave out the import and style the page yourself.
• Elements: pass React Markdown components to RootSmithPage to replace elements such as links, headings, or code blocks.
• Images: images load only from your site's origin by default. Pass imageOrigins={["https://cdn.example.com"]} to allow other hosts.
• CDN caches: pass a refresh function to purge your own cache. Call revalidateTag(rootSmithTag, { expire: 0 }) in it too, and finish before it returns.

import { revalidateTag } from "next/cache"
import { createRootSmithHandler, rootSmithTag } from "@rootsmithio/next"

export const POST = createRootSmithHandler({
  refresh: async (path) => {
    revalidateTag(rootSmithTag, { expire: 0 })
    await purgeMyCdn(path)
  },
})

Markdown supports headings, lists, links, URL images, quotes, fenced code, tables, and task lists. Raw HTML is skipped, unsafe URL schemes are removed, and no MDX or JavaScript runs.

ReferenceCopy Anchor Link

@rootsmithio/nextCopy Anchor Link

The client throws for other HTTP failures and invalid responses.

@rootsmithio/next/markdownCopy Anchor Link

PublishedPageCopy Anchor Link

interface PublishedPage {
  id: string
  siteId: string
  pageTypeId: string
  revision: number
  title: string
  path: string
  description: string
  markdown: string
  url: string
  publishedAt: string
  updatedAt: string
}