@no-mess/client

TypeScript SDK for the no-mess headless CMS.

Install

npm install @no-mess/client
# or
bun add @no-mess/client

Schema Builder

Use @no-mess/client/schema to define route-bound templates, reusable fragments, and recursive fields:

import {
  defineFragment,
  defineSchema,
  defineTemplate,
  field,
} from "@no-mess/client/schema";

const imageWithAlt = defineFragment("image-with-alt", {
  name: "Image With Alt",
  fields: {
    image: field.image({ required: true }),
    alt: field.text(),
  },
});

const homePage = defineTemplate("home-page", {
  name: "Home Page",
  mode: "singleton",
  route: "/",
  fields: {
    hero: field.object({
      fields: {
        headline: field.text({ required: true }),
        slides: field.array({
          of: field.fragment(imageWithAlt),
          minItems: 1,
        }),
      },
    }),
  },
});

export default defineSchema({
  contentTypes: [imageWithAlt, homePage],
});

defineContentType() remains available as a compatibility alias for template definitions, but new code should prefer defineTemplate() and defineFragment().

Fetch Content

import { createNoMessClient } from "@no-mess/client";

const client = createNoMessClient({
  apiKey: process.env.NO_MESS_API_KEY!,
});

const posts = await client.getEntries("blog-post");
const post = await client.getEntry("blog-post", "hello-world");
const maybePost = await client.getEntryOrNull("blog-post", "missing");

Next.js Helpers

For Next.js apps, prefer the dedicated env-backed helpers:

import { createServerNoMessClient } from "@no-mess/client/next";
import { getShopifyHandle } from "@no-mess/client";

const cms = createServerNoMessClient({
  fetch: { cache: "no-store" },
});
const homePage = await cms.getSingleton("home-page");

const featuredHandles =
  homePage?.featuredProducts
    ?.map((item) => getShopifyHandle(item.product))
    .filter(Boolean) ?? [];

For browser-side no-mess fetches that should use your publishable key:

import { createBrowserNoMessClient } from "@no-mess/client/next";

const client = createBrowserNoMessClient();
const posts = await client.getEntries("blog-post");

createServerNoMessClient() reads:

• NO_MESS_API_KEY
• NO_MESS_API_URL
• NEXT_PUBLIC_NO_MESS_API_URL
• DEFAULT_API_URL

createBrowserNoMessClient() reads:

• NEXT_PUBLIC_NO_MESS_PUBLISHABLE_KEY
• NEXT_PUBLIC_NO_MESS_API_URL
• DEFAULT_API_URL

Both helpers throw when the required key is missing.

Deployed runtime delivery

For deployed routes that should reflect CMS publishes immediately and support route-aware Live Edit, fetch content at request time:

import { createServerNoMessClient } from "@no-mess/client/next";

export const cms = createServerNoMessClient({
  fetch: { cache: "no-store" },
});

This appends fresh=true to content API reads, bypasses no-mess-side GET caches, and avoids build-time content snapshots on deployed routes.

If your route is fully statically generated, exported, or relies on build-only slug generation, new routes still will not exist until you redeploy even though existing runtime routes can fetch fresh content.

Shopify Refs

CMS Shopify fields store raw refs, not expanded Shopify records:

type ShopifyProductRef = string | { handle: string };
type ShopifyCollectionRef = string | { handle: string };

Use the helper below to read the handle from either shape:

import { getShopifyHandle } from "@no-mess/client";

const handle = getShopifyHandle(entry.featuredProduct);

If you want synced Shopify records inline, opt into expansion:

const post = await client.getEntry("blog-post", "hello-world", {
  expand: ["shopify"],
});

Preview-Only Route

Use this when you want a dedicated /no-mess-preview page.

"use client";

import { NoMessPreview } from "@no-mess/client/react";

export default function PreviewPage() {
  return (
    <NoMessPreview apiKey={process.env.NEXT_PUBLIC_NO_MESS_PUBLISHABLE_KEY!}>
      {({ entry, error, isLoading }) => {
        if (isLoading) return <p>Loading preview...</p>;
        if (error) return <p>{error.message}</p>;
        if (!entry) return null;

        return <h1>{entry.title}</h1>;
      }}
    </NoMessPreview>
  );
}

Route-Aware Preview and Live Edit

This is the recommended integration path. It lets the dashboard open real site routes, overlay the current working draft before publish, and store reported page URLs per entry.

1. Wrap the route tree

"use client";

import { NoMessLiveRouteProvider } from "@no-mess/client/react";

export default function SiteLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <NoMessLiveRouteProvider
      apiKey={process.env.NEXT_PUBLIC_NO_MESS_PUBLISHABLE_KEY!}
    >
      {children}
    </NoMessLiveRouteProvider>
  );
}

2. Bind the rendered entry

"use client";

import {
  NoMessField,
  useNoMessEditableEntry,
} from "@no-mess/client/react";

export function BlogArticle({ entry }) {
  const editableEntry = useNoMessEditableEntry(entry);

  return (
    <article>
      <NoMessField as="h1" name="title">
        {editableEntry.title}
      </NoMessField>
      <NoMessField as="div" name="body">
        {editableEntry.body}
      </NoMessField>
    </article>
  );
}

On deployed routes, the server component should fetch the entry with runtime delivery and pass it to a client component that calls useNoMessEditableEntry(entry).

useNoMessEditableEntry() automatically:

• swaps in the current working draft for the active iframe session
• applies live field overrides from Live Edit before publish
• reports the current URL for route-aware reopening
• emits the entry-bound signal used by dashboard warnings

The rendered route must also allow the dashboard origin in CSP:

const nextConfig = {
  async headers() {
    return [
      {
        source: "/blog/:path*",
        headers: [
          {
            key: "Content-Security-Policy",
            value: "frame-ancestors 'self' https://admin.no-mess.xyz",
          },
        ],
      },
    ];
  },
};

Manual Route Reporting

If you need custom reporting logic, call the client method directly:

import { createBrowserNoMessClient } from "@no-mess/client/next";

const client = createBrowserNoMessClient();

await client.reportLiveEditRoute({
  entryId: "entry_123",
  url: window.location.href,
});

API Reference

Content

| Method | Description | |--------|-------------| | client.getSchemas() | List all template and fragment schemas | | client.getSchema(typeSlug) | Get a single schema by slug | | client.getEntries(contentType, options?) | Fetch all published entries of a template | | client.getEntry(contentType, slug, options?) | Get a single entry by slug | | client.getEntryOrNull(contentType, slug, options?) | Return null instead of throwing on 404 | | client.getSingleton(contentType, options?) | Fetch the first published entry for a singleton-like content type | | client.getRequiredSingleton(contentType, options?) | Like getSingleton() but throws a 404-style NoMessError when missing | | getShopifyHandle(ref) | Extract a Shopify handle from a raw ref |

For content reads, options.fetch forwards cache-related fetch options and options.fresh explicitly appends fresh=true to bypass no-mess-side GET caches.

Preview / Live Edit

| Method | Description | |--------|-------------| | client.exchangePreviewSession(session) | Exchange a preview session token for draft content | | client.reportLiveEditRoute({ entryId, url? }) | Report the current page URL for route-aware Live Edit |

React (@no-mess/client/react)

| API | Description | |-----|-------------| | NoMessPreview | Preview-only route wrapper | | useNoMessPreview(config) | Hook alternative for preview-only pages | | NoMessLiveRouteProvider | Route-aware provider for real site routes | | useNoMessEditableEntry(entry, options?) | Returns the active draft entry and reports the route | | NoMessField | Convenience component for data-no-mess-field annotations | | useNoMessField(fieldName) | Read a single field override from provider context |

Migration

If you already use useNoMessPreview() and useNoMessLiveEdit() on /no-mess-preview:

1. Keep the existing preview route in place.
2. Add NoMessLiveRouteProvider to the real route tree.
3. Replace direct entry rendering with useNoMessEditableEntry(entry) on the routes you want Live Edit to open.
4. Add data-no-mess-field annotations or NoMessField wrappers.

If you do nothing, the legacy preview route keeps working. You only miss the route-aware Live Edit workflow with working-draft previews on real routes.

License

MIT