Client for Next.js

createClient

Creates the preview-aware client - bind it once at module scope and use it from any Server Component, Route Handler or Server Action:

// lib/cairn.ts
import { createClient } from "@cairn-cms/client/next";
export const cairn = createClient({ projectId: process.env.NEXT_PUBLIC_CAIRN_PROJECT_ID! });

// app/posts/[slug]/page.tsx
const [post] = await cairn.fetch("post", { where: { slug }, include: ["author"], limit: 1 });
const hero = await cairn.image(post.heroImage, { size: "large" });

The Draft Mode/cookie check runs at most once per request (React cache()), and only reads the cookie once Draft Mode is on - so ordinary visitors don't turn statically rendered pages dynamic. If a preview session has expired or been revoked, reads quietly fall back to published content instead of failing the page. Server-only: the session cookie is HttpOnly, so a Client Component gets data passed down as props.

function createClient(config: CreateClientConfig): CairnNextClient

Returns: CairnNextClient

createPreviewExitHandler

Builds the GET handler for exiting preview mode - mount at app/api/preview/exit/route.ts, and link to it (e.g. from PreviewBanner's exit action) at whatever path that ends up being:

export const GET = createPreviewExitHandler();

function createPreviewExitHandler(config: CreatePreviewExitHandlerConfig): (request: NextRequest) => Promise<Response>

Returns: (request: NextRequest) => Promise<Response>

createPreviewHandler

Builds the GET handler for your preview route (ROADMAP.md §4) - mount it at whatever path you set as this project's Preview URL in Settings, e.g. app/api/preview/route.ts:

export const GET = createPreviewHandler({
  projectId: process.env.NEXT_PUBLIC_CAIRN_PROJECT_ID,
  resolvePath(resolution) {
    if (resolution.documentType === "post") return `/blog/${resolution.documentId}`;
    return "/";
  },
});

Handles everything else itself: exchanging either the single-use internal grant or reusable external share credential in the ?token= param (a 401 if it is missing, invalid, expired, or already used where applicable), turning on Next's draft mode, remembering the *session* token (not the grant) in its own HttpOnly cookie so later requests can still read draft content, and redirecting.

function createPreviewHandler(config: CreatePreviewHandlerConfig): (request: NextRequest) => Promise<Response>

Returns: (request: NextRequest) => Promise<Response>

PreviewBanner

Drop this in your root layout - it renders nothing outside preview mode, so it's always safe to include unconditionally:

import { PreviewBanner } from "@cairn-cms/client/next";

export default function RootLayout({ children }) {
  return (
    <html><body>
      {children}
      <PreviewBanner projectId={process.env.NEXT_PUBLIC_CAIRN_PROJECT_ID} />
    </body></html>
  );
}

Inside preview mode, shows a small fixed banner with an exit link and mounts the live-reload connection (see PreviewLiveReload) - the Dashboard saving something now shows up without a manual refresh.

function PreviewBanner(__namedParameters: PreviewBannerProps): Promise<Element | null>

Returns: Promise<Element | null>

CreateClientConfig

CreatePreviewExitHandlerConfig

CreatePreviewHandlerConfig

DeliveredDocument

A delivered document from either API - _publishedAt is null only for a never-published draft seen in preview. What @cairn-cms/client/next's createClient returns, since one call can be served by either side.

type DeliveredDocument<T> = PreviewDocument<T>

FetchOneOptions

The subset of FetchOptions fetchOne/fetchSingleton accept.

FetchOptions

Options for fetch() - filters (ANDed together), field selection, one one-hop reference resolution, sorting, and pagination. Compiles down to the query params apps/api's /published/types/:type/documents route accepts (see packages/db/src/publishedQuery.ts) - this just spares callers from hand-building that query string themselves.

ImageValue

What an image field's value looks like in document data - see @cairn-cms/schema's validator.

PreviewBannerProps

PreviewImageUrlOptions

imageUrl()'s only option in preview mode - a named preset, or omit for the original. Unlike createImageUrl, there's no API-route fallback for anything else (no apiUrl transform path exists on the preview side) - fit/format/quality/explicit dimensions simply aren't offered here.

PreviewResolution

What GET .../preview/resolve reports once a token verifies - see apps/api's routes/preview.ts. documentType/documentId are null for a token minted without one (e.g. previewing a whole dataset/branch rather than jumping to one document).