@digistra/cms

Runtime CMS SDK for Digistra applications.

Install

npm install @digistra/cms @digistra/auth

Setup

// cms.config.ts (server-side only)
import { defineDigistraCms } from "@digistra/cms";

defineDigistraCms({ slug: "your-instance-slug" });

In development, the mock adapter is used automatically (requires Node.js runtime). In production, requests go to https://cms.digistra.dev.

Core API

Import the generated client (recommended):

import { cmsClient } from "@digistra/cms/generated";

Or use the low-level helpers directly:

import { getContent, uploadContent, getMedia, uploadMedia } from "@digistra/cms";

getContent(path, options?)

Returns the content stored at the given path.

• Media fields are returned as alt text strings — not URLs.
• Use getMedia if you need the media URL.

const page = await cmsClient.homePage.getContent();
console.log(page.title);      // string
console.log(page.heroImage);  // alt text string, NOT a URL

setContent(path, data)

Uploads content to the backend.

• Returns void on success.
• Throws an Error on failure. Wrap in try/catch.
• Does not return data. Call getContent again after writing.

await cmsClient.homePage.setContent({ title: "New title" });
const updated = await cmsClient.homePage.getContent({ cache: "force" });

getMedia(path, options?)

Returns the URL for a media field.

• In production: returns the absolute backend URL (or a local proxy URL if mediaProxyPath is configured).
• In dev/mock mode: returns a URL served by the local API route created by npx digistra cms init (e.g. /api/dev-cms-media/{path}).
• Throws if the URL cannot be resolved.

const heroUrl = await cmsClient.homePage.heroImage.getMedia();
// → "https://cms.digistra.dev/read/my-slug/media/home-page-heroImage.jpg"
// → "/api/dev-cms-media/home-page-heroImage" (dev mode)

setMedia(path, file)

Uploads a media file to the backend.

• Returns void on success.
• Throws an Error on failure. Wrap in try/catch.
• Does not return data. Call getMedia again after writing.

await cmsClient.homePage.heroImage.setMedia(file);
const updatedUrl = await cmsClient.homePage.heroImage.getMedia({ cache: "force" });

Pattern: Write then read

Write operations return no data. Always fetch again after a write:

// Write
await cmsClient.homePage.setContent({ title: "Hello" });

// Read back with fresh data
const content = await cmsClient.homePage.getContent({ cache: "force" });

// Write media
await cmsClient.homePage.heroImage.setMedia(file);

// Read back the URL
const url = await cmsClient.homePage.heroImage.getMedia({ cache: "force" });

Cache modes

getContent and getMedia accept an optional cache option:

| Mode | Behaviour | |------|-----------| | "default" | Cache-first. Fetches on miss, caches result. Good for public pages. | | "force" | Always fetch fresh. Updates cache. Good for admin/preview. | | "no-store" | Always fetch fresh. Never writes to cache. Good for debugging. |

await cmsClient.homePage.getContent({ cache: "force" });
await cmsClient.homePage.heroImage.getMedia({ cache: "no-store" });

Dev / mock mode

In development (NODE_ENV !== "production"), the mock adapter is used automatically.

• Content is read from digistra/cms/mock.json (synced to node_modules/.cache/digistra/).
• Media files are read from digistra/cms/mediamock/.
• getMedia returns URLs in the form /api/dev-cms-media/{path} — served by a local API route.
• setMedia stores files in the mock cache directory.

Initialize the dev structure:

npx digistra cms init

This creates:

• digistra/cms/mock.json — content data
• digistra/cms/maps/ — schema definitions
• digistra/cms/mediamock/ — media files
• src/app/api/dev-cms-media/[...path]/route.ts — local API route for serving mock media

CLI

npx digistra cms init       # Initialize project structure and local API route
npx digistra cms generate   # Generate TypeScript types and cmsClient
npx digistra cms check-mock # Validate mock.json against schemas
npx digistra cms upload     # Upload schemas to backend
npx digistra cms clean      # Remove all generated files

Exports

| Import path | Contents | |---|---| | @digistra/cms | Core SDK: defineDigistraCms, getContent, uploadContent, getMedia, uploadMedia | | @digistra/cms/generated | Auto-generated cmsClient (run cms generate first) | | @digistra/cms/mock | mockAdapter, mockAdapterByEnv, seed helpers | | @digistra/cms/next | Next.js cache helpers | | @digistra/cms/ui | React UI components (CMSOverlay, ContentEditor, MediaUploader) |

Mock data format

{
  "homePage": {
    "title": "Welcome",
    "heroImage": {
      "file": "hero.jpg",
      "alt": "Hero banner"
    }
  }
}

• getContent() returns heroImage as the alt text string ("Hero banner").
• getMedia("home-page-heroImage") returns the URL for hero.jpg.

Schema definition

Schema files live in digistra/cms/maps/. File names become camelCase client keys:

home-page.json → cmsClient.homePage
product.json   → cmsClient.product

Field types: string, number, boolean, object, array, media.

{
  "title": { "type": "string" },
  "heroImage": { "type": "media", "mediaType": "image" }
}