@backendfree/cms

Pages, typed: what is published, or with a test key the drafts. A publishable key is enough for the pages: nothing there is private, it is what the website shows. Reading the image library takes a secret key (see Images).

npm install @backendfree/core @backendfree/cms

import { Client } from '@backendfree/core';
import { Cms, firstSection, sectionsOfType } from '@backendfree/cms';

const cms = new Cms(new Client({ origin: 'https://backendfree.com', key: 'pk_live_...' }));

const home = await cms.page('home');
const hero = firstSection(home, 'hero');
const blocks = sectionsOfType(home, 'text');

Everything here reads. Content is edited in the dashboard and published from there, and an API that could write it would be a second way to change a live site.

Sections are per project

A page is a list of sections, and what section types exist is decided per project in the dashboard: hero, services, faq, or whatever you defined. So Section is { type: string, ...fields } and narrowing it is your job.

The standard types every project starts with, each field's key, kind and whether it is required, are listed at backendfree.com/docs/sections.

interface Hero {
  type: 'hero';
  headingLead: string;
  headingAccent: string;
  ctaPrimary: { label: string; href: string };
}

const hero = firstSection<Hero>(home, 'hero');

A section of a type your build has never heard of is skipped rather than rendered wrongly, so you can add one to the schema before the frontend learns it.

Field values are the seven kinds and nothing else: a string, a paragraph, a list of strings, a {label, href} link, a boolean, an image, or a list of groups of those. That ceiling is deliberate.

Images

An image field arrives as { id, url, width, height, alt }, an image of the website's library as it is now, or null when none is chosen or the image was deleted since. alt may be empty. The type is ImageValue.

import type { ImageValue } from '@backendfree/cms';

interface Team {
  type: 'team';
  heading: string;
  photo: ImageValue;
}

const team = firstSection<Team>(home, 'team');
if (team?.photo) {
  const { url, width, height, alt } = team.photo;
}

The library itself is read with a secret key, from your server: images() lists it newest first and image(id) reads one. Both throw before asking when the client holds a publishable key, since the library holds images no page shows yet. Images are uploaded in the dashboard, on the Media screen.

const server = new Cms(new Client({ origin: 'https://backendfree.com', key: process.env.BACKENDFREE_SECRET_KEY! }));

const { results } = await server.images();
const one = await server.image(results[0].id);

Drafts

With a live key, a draft, a page in another language, and a page that never existed all answer the same 404. That is on purpose: the API is not a way to discover what a client is still working on.

With a test key the drafts are the content: every page as it was last saved, published or not, so a staging site shows a change before it goes live. version and published_at are null on a page never published. Anybody who can open a site using a test key can read the unpublished work through it.

import { isNotFound } from '@backendfree/core';

const page = await cms.page(slug).catch((error) => {
  if (isNotFound(error)) return null;
  throw error;
});

Knowing when to rebuild

manifest() is one cheap call whose cache_version changes on every publish, and with a test key whenever a draft is saved. Keep the last number you saw and refetch only when it moves, rather than refetching everything on a timer.

const { cache_version } = await cms.manifest();
if (cache_version !== lastSeen) { /* rebuild */ }

It also says which locales have something published, and which the project is set up to publish, which are not the same list.