NextS3 CMS SDK

The NextS3 CMS SDK is a tiny JavaScript helper that knows how to talk to the NextS3 Headless CMS. It hides the S3 key structure, exposes a one-line API for querying public content, and includes authenticated helpers for provisioning models, teams, and content from any JavaScript runtime that supports the standard fetch API (Node.js 18+, Next.js, Cloudflare Workers, etc.).

Installation

npm install cms-sdk
# or
pnpm add cms-sdk
# or
yarn add cms-sdk

The package ships unbundled ES modules. When using CommonJS, import with dynamic import() or transpile with your build pipeline.

Client Configuration

import { CMSClient } from "cms-sdk";

const cms = new CMSClient({
  bucketUrl: "https://your-bucket.s3.amazonaws.com",
  websiteId: "website_123",
  teamId: "team_abc",
  apiUrl: "https://cms.example.com/api/cms", // optional, defaults to http://localhost:3000/api/cms
  apiKey: process.env.CMS_API_KEY,           // optional, only required for admin actions
  revalidate: 120                            // optional, Next.js cache hint (seconds)
});

| Option | Required | Description | | :--- | :--- | :--- | | bucketUrl | ✅ | Base URL of the public S3 bucket or CloudFront distribution. | | websiteId | ✅ | Website slug used when persisting content inside public-data/<websiteId>. | | teamId | ✅ | Needed for write operations and model administration. | | apiUrl | ❌ | CMS API origin that exposes /api/cms/* routes. | | apiKey | ❌ | Bearer token injected into Authorization for privileged calls. | | revalidate | ❌ | Next.js cache revalidation time in seconds (defaults to 60). |

Reading Published Content (No Auth)

Public data lives entirely in your bucket under public-data/<websiteId>/<model>/. The SDK issues direct fetches against that path, so you can use it in static builds, ISR routes, or server actions without touching the admin API.

const posts = await cms.getAll("blog-posts");  // reads blog-posts/index.json
const post = await cms.get("blog-posts", "welcome-post");

Both helpers return null when the object does not exist. Wrap calls in your preferred error or fallback logic.

Modeling & Draft Content (Requires API Access)

When you provide apiKey, the client automatically attaches Authorization: Bearer <apiKey> to every request hitting /api/cms. These helpers let you drive the CMS UI actions programmatically:

• getModels(), createModel(modelData), updateModel(modelData), deleteModel(slug)
• getDraftContent(modelSlug)
• createContent(modelSlug, data, id?, action?) where action can be draft or publish
• createTeam(name), getTeams()
• createWebsite(teamId, name, domain), getWebsites(teamId)
• getModelTypes() - fetches /api/cms/model/types to discover supported field definitions and validation requirements.

All methods throw when the API responds with a non-2xx status, so you can try/catch to display admin-friendly errors.

Example getStaticProps Usage

import { CMSClient } from "cms-sdk";

const cms = new CMSClient({
  bucketUrl: process.env.NEXT_PUBLIC_S3_DOMAIN,
  websiteId: "marketing",
  teamId: "marketing-team"
});

export async function getStaticProps() {
  const posts = await cms.getAll("blog-posts");
  return { props: { posts } };
}

Running in Edge/Serverless

• The SDK relies solely on the global fetch, so it works in Vercel Edge Functions, Cloudflare Workers, and other runtime environments without extra polyfills (ensure fetch exists).
• When running inside Next.js, the optional revalidate hint integrates with the App Router cache.
• For environments that require strict CORS, ensure your bucket or CDN allows requests from the domain that executes this SDK.

Troubleshooting

• null responses for published content usually mean the file is missing in public-data/<websiteId>/<model>/.... Double-check your publish workflow.
• Failed to fetch ... errors indicate the API route rejected the request (expired API key, wrong team/website ID, or the route is not reachable). Inspect the thrown error message for the HTTP status text.
• Stale content can occur if a CDN caches aggressively. Lower revalidate or use cache-busting query params when necessary.