Package Exports

@utilsy/cms-nextjs
@utilsy/cms-nextjs/react

Readme

@utilsy/cms-nextjs

Headless Next.js SDK for Utilsy gateway-cms public CMS APIs: blog (/public/blog) and dynamic content types (/public/api). Provides a typed HTTP client, domain mappers, server-friendly fetch helpers, and React data hooks—bring your own UI.

Install

npm install @utilsy/cms-nextjs

Peer dependencies: react ^18 or ^19. next is optional (only needed if you pass next.revalidate to fetch).

Quick start

1. Create a client

Direct gateway-cms (default path prefix):

import { createCmsClient } from "@utilsy/cms-nextjs";

export const cms = createCmsClient({
  baseUrl: process.env.NEXT_PUBLIC_CMS_BASE_URL!,
  siteId: process.env.NEXT_PUBLIC_CMS_SITE_ID,
});

Main API gateway (prefix before /public/blog and /public/api):

export const cms = createCmsClient({
  baseUrl: process.env.NEXT_PUBLIC_CMS_BASE_URL!,
  siteId: process.env.NEXT_PUBLIC_CMS_SITE_ID,
  pathPrefix: "/api/backend/cms",
});

2. Server Component (list posts)

import { cms } from "@/lib/cms";

export default async function BlogPage() {
  const result = await cms.blog.listMappedPosts(
    { page: 1, limit: 20 },
    { next: { revalidate: 60 } },
  );

  if (!result?.posts.length) {
    return <p>No posts yet.</p>;
  }

  return (
    <ul>
      {result.posts.map((post) => (
        <li key={post.postId}>
          <a href={`/blog/${post.slug}`}>{post.title}</a>
        </li>
      ))}
    </ul>
  );
}

3. Server Component (filtered content by type)

import { cms } from "@/lib/cms";

export default async function ServicesPage() {
  const result = await cms.content.listMappedEntries(
    "services",
    { page: 1, limit: 12, filters: { featured: true } },
    { next: { revalidate: 60, tags: ["cms:services"] } },
  );

  if (!result?.entries.length) {
    return <p>No services yet.</p>;
  }

  return (
    <ul>
      {result.entries.map((entry) => (
        <li key={entry.id}>
          <a href={`/services/${entry.data.slug}`}>{String(entry.data.title ?? "")}</a>
        </li>
      ))}
    </ul>
  );
}

4. Client engagement (likes & comments)

"use client";

import { CmsProvider, useBlogLike, useBlogComments } from "@utilsy/cms-nextjs/react";
import { cms } from "@/lib/cms";

export function PostEngagement({ postId }: { postId: string }) {
  return (
    <CmsProvider client={cms}>
      <Engagement postId={postId} />
    </CmsProvider>
  );
}

function Engagement({ postId }: { postId: string }) {
  const { liked, likeCount, toggle, toggling } = useBlogLike(postId);
  const { comments, submitComment, submitting } = useBlogComments(postId);

  return (
    <div>
      <button type="button" onClick={toggle} disabled={toggling}>
        {liked ? "Unlike" : "Like"} ({likeCount})
      </button>
      <ul>
        {comments.map((c) => (
          <li key={c.id}>{c.name}: {c.message}</li>
        ))}
      </ul>
    </div>
  );
}

5. Lead capture (custom form via Server Action)

Use a LEAD_CAPTURE content type in CMS (with field mapping configured). Submit from your own form UI—no hosted-form embed.

// app/actions/submit-lead.ts
"use server";

import { cms } from "@/lib/cms";

export async function submitContactLead(data: Record<string, unknown>) {
  return cms.leads.submit("contact-enquiries", data);
}

"use client";

import { submitContactLead } from "@/app/actions/submit-lead";

export function ContactForm() {
  return (
    <form
      action={async (formData) => {
        await submitContactLead({
          firstName: String(formData.get("firstName") ?? ""),
          email: String(formData.get("email") ?? ""),
          message: String(formData.get("message") ?? ""),
        });
      }}
    >
      {/* your fields */}
    </form>
  );
}

Optional honeypot: include _honeypot in data; submissions with a non-empty value are rejected.

Use your own signup / preference-center UI—no hosted form embed.

// app/actions/newsletter.ts
"use server";

import { cms } from "@/lib/cms";

export async function subscribeNewsletter(email: string) {
  return cms.newsletter.subscribe({ email, source: "footer" });
}

export async function unsubscribeNewsletter(email: string) {
  return cms.newsletter.unsubscribe({ email });
}

export async function updateNewsletterPrefs(
  token: string,
  customFields: Record<string, unknown>,
) {
  return cms.newsletter.updatePreferences({ token, customFields });
}

"use client";

import { CmsProvider, useNewsletterSubscribe } from "@utilsy/cms-nextjs/react";
import { cms } from "@/lib/cms";

export function NewsletterSignup() {
  return (
    <CmsProvider client={cms}>
      <NewsletterSignupInner />
    </CmsProvider>
  );
}

function NewsletterSignupInner() {
  const { subscribe, submitting, error } = useNewsletterSubscribe();

  return (
    <form
      onSubmit={async (e) => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        await subscribe({ email: String(fd.get("email") ?? "") });
      }}
    >
      <input name="email" type="email" required />
      <button type="submit" disabled={submitting}>Subscribe</button>
      {error && <p>{error.message}</p>}
    </form>
  );
}

Confirmation links from email hit GET /public/newsletter/confirm/:token (no siteId required on the server; the SDK still sends siteId when configured).

7. Client content list (hooks)

"use client";

import { CmsProvider, useContentEntries } from "@utilsy/cms-nextjs/react";
import { cms } from "@/lib/cms";

export function ServicesList() {
  return (
    <CmsProvider client={cms}>
      <ServicesListInner />
    </CmsProvider>
  );
}

function ServicesListInner() {
  const { entries, loading, error } = useContentEntries("services", {
    page: 1,
    limit: 20,
  });

  if (loading) return <p>Loading…</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {entries.map((e) => (
        <li key={e.id}>{String(e.data.title ?? "")}</li>
      ))}
    </ul>
  );
}

Environment variables

Variable	Description
`NEXT_PUBLIC_CMS_BASE_URL`	Gateway or API base URL (no trailing slash)
`NEXT_PUBLIC_CMS_SITE_ID`	CMS site Mongo id — recommended when Host does not match a CMS domain
`NEXT_PUBLIC_CMS_PATH_PREFIX`	Optional, e.g. `/api/backend/cms`

Site resolution

The CMS resolves the site from:

?siteId= query param (SDK appends this when siteId is configured), or
Host / x-origin header matching a registered domain.

For local dev or gateway-only deployments, always set siteId in the client config.

Content types and filters

Endpoint: GET /public/api/{contentTypeApiId} (published entries only).
Content types must have apiAccess: PUBLIC.
filters are exact matches on data.<field> (JSON query param). Example: { category: "news" }.
Use contentTypeApiId (kebab-case slug from CMS), not the Mongo content type id.

COMPONENT and DYNAMIC_ZONE fields

Published entry data may include nested structures from the CMS builder:

Field type	Shape in `entry.data`
COMPONENT (single)	`{ title: "…", … }`
COMPONENT (repeatable)	`[{ … }, { … }]`
DYNAMIC_ZONE	`[{ __component: "<apiId>", …fields }, …]`

Helpers (no extra API calls):

import {
  getComponentItems,
  getDynamicZoneBlocks,
  filterDynamicZoneByComponent,
  parseContentTypeFields,
} from "@utilsy/cms-nextjs";

const entry = await cms.content.getMappedEntry("landing", "home");
if (!entry) return;

const slides = getComponentItems(entry, "slides");
const ctas = filterDynamicZoneByComponent(
  getDynamicZoneBlocks(entry, "blocks"),
  "cta",
);

// Optional: inspect schema from populated contentType on the entry DTO
const fields = parseContentTypeFields(entry.contentType?.fields);

Types: FieldType, ContentTypeField, DynamicZoneBlock, ContentTypeCategory.

API reference

Client (`createCmsClient`)

Blog

Method	Description
`blog.listPosts(query?, init?)`	Paginated list (summary fields only)
`blog.getPostBySlug(slug, init?)`	Full post DTO
`blog.listCategories(init?)`	Active categories
`blog.listComments(postId, init?)`	Approved comments
`blog.createComment(postId, body)`	Create comment (throws on error)
`blog.getEngagement(postId, { visitorId? }, init?)`	Stats + `likedByMe`
`blog.toggleLike(postId, { visitorId? })`	Toggle like
`blog.listMappedPosts(...)`	List + `mapCmsPostToBlogPost`
`blog.getMappedPostBySlug(...)`	Single mapped `BlogPost`
`blog.listMappedCategories(...)`	Mapped categories
`blog.listMappedComments(...)`	Mapped comments

Content

Method	Description
`content.listEntries(contentTypeApiId, query?, init?)`	Paginated raw DTOs
`content.getEntry(contentTypeApiId, idOrSlug, init?)`	Single raw DTO
`content.listMappedEntries(...)`	List + `mapCmsEntryToContentEntry`
`content.getMappedEntry(...)`	Single mapped `ContentEntry`
`content.getSingleMappedEntry(...)`	First mapped entry for SINGLE types (`limit=1`)

Query params for listEntries / listMappedEntries: page, limit, search, sort, order, filters (object). For SINGLE content types the public API caps limit at 1 and may include category: "SINGLE" and maxEntries: 1 in the list response.

Single content types

Use a CMS content type with category SINGLE for one document per site (homepage settings, global SEO, etc.). Admin creates the type and edits the auto-created draft on the Content tab.

// Prefer for singleton types — no entry id/slug required
const settings = await client.content.getSingleMappedEntry("site-settings");

// Or with React
const { entry, loading } = useSingleContentEntry("site-settings");

listEntries / listMappedEntries still work; pass limit: 1 or use getSingleMappedEntry.

Helpers: serializeContentFilters, mapCmsEntryToContentEntry, getComponentItems, getDynamicZoneBlocks, filterDynamicZoneByComponent, parseContentTypeFields.

Leads

Method	Description
`leads.submit(contentTypeApiId, data, options?)`	Submit lead fields; creates content entry + CRM enquiry (throws on error)

Endpoint: POST /public/api/{contentTypeApiId}/submissions
Content type must be LEAD_CAPTURE and apiAccess: PUBLIC
Field keys in data must match the content type schema; CRM mapping uses leadCaptureConfig in admin

Method	Description
`newsletter.subscribe(input, init?)`	Subscribe by email; may send confirmation email
`newsletter.unsubscribe(input, init?)`	Unsubscribe by `token` (from email) or `email`
`newsletter.confirm(token, init?)`	Confirm subscription from email link
`newsletter.updatePreferences(input, init?)`	Update `customFields`, `tags`, and/or `listId`

Base path: /public/newsletter (plus optional pathPrefix)
subscribe: email required; optional source, listId, customFields
unsubscribe / updatePreferences: provide token or email
updatePreferences: at least one of customFields, tags, or listId; optional tagsAction (set | add | remove)

React (`@utilsy/cms-nextjs/react`)

Export	Description
`CmsProvider`	Context for hooks
`useCmsClient`	Access client instance
`useVisitorId` / `getVisitorId`	Anonymous visitor id for likes
`useBlogEngagement`	Load engagement stats
`useBlogLike`	Like toggle + counts
`useBlogComments`	List + submit comments
`useContentEntries`	List mapped entries by content type
`useContentEntry`	Single mapped entry by id or slug
`useSingleContentEntry`	Mapped entry for SINGLE types (no id/slug)
`useSubmitLead`	Submit lead from client (prefer Server Action for forms)
`useNewsletterSubscribe`	Subscribe from client (prefer Server Action)
`useNewsletterUnsubscribe`	Unsubscribe by token or email
`useNewsletterUpdatePreferences`	Update subscriber preferences
`useNewsletterConfirm`	Confirm subscription token (e.g. preference page)

CORS

Public CMS reads from the browser require either:

Same-origin proxy (e.g. Next.js Route Handler forwarding to gateway), or
Server Components / Route Handlers calling the SDK server-side.

Mutations (comments, likes, lead submit, newsletter subscribe/unsubscribe/preferences) should run server-side (Server Action / Route Handler) or via a same-origin proxy with CORS configured on the gateway.

License

MIT