Shapio blog

Content that is code: using Shapio's code field

Thu, 08 Oct 2026 00:00:00 GMT

Would you open this value in a code editor? Then it is a code field.

A dialogue script, a runtime configuration file or an HTML embed is content that is code. It has syntax. Its whitespace may matter. Another program consumes it. A product's price or a post's title belongs in a normal field.

Shapio's new code field stores a string. It never trims, reformats or rewrites that string. Bytes in equal bytes out. The language setting tells the editor and API what kind of text the field contains.

Here are three ways to use it, starting with the program that consumes the content.

A game: dialogue written by the writer

A writer can keep a dialogue script in the CMS. The game downloads the string and passes it to its dialogue runtime for parsing.

For example, an ink script might contain:

=== gatekeeper ===
The gatekeeper lowers her lantern.
* [Ask about the road]
    "Stay east of the river."
    -> END
* [Leave]
    -> END

Create a code field and set its language to plain. Ink, Yarn and Lua are not language options yet. Plain gives the writer a monospaced editor and line numbers, without syntax highlighting.

That choice does not change the stored script. Shapio preserves the line breaks, indentation and punctuation exactly as entered. The game receives the string through REST and gives it to the runtime that understands ink.

The API also describes the field's language. With plain, that metadata identifies plain code text, not ink specifically. The game still needs to know which dialogue parser to use. The language setting describes the field; it does not select a runtime.

The admin uses CodeMirror. Tab moves focus to the next control, just as it does elsewhere in the admin. To indent, use Cmd-] and Cmd-[, or Ctrl-] and Ctrl-[ on Windows and Linux.

An app or engine: configuration its runtime already reads

A code field also fits configuration that an app or engine already reads as JSON or YAML. Think drop rates, feature flags or wave timings.

For a JSON configuration field, set the language to json and turn on Require valid JSON. An editor could maintain:

{
  "dropRate": 0.15,
  "features": {
    "bonusRound": true
  },
  "waveTimings": [0, 15, 30]
}

The runtime downloads the string and parses it as it would its existing JSON configuration. Shapio does not turn those keys into separate fields. The value remains one string.

Now suppose someone removes the comma after the drop rate:

{
  "dropRate": 0.15
  "features": {
    "bonusRound": true
  }
}

With the parse check enabled, the field shows "Must be valid JSON" before saving. The server refuses the invalid value too. That bad edit cannot become the saved configuration that the app downloads.

The check establishes that the value parses as JSON. It does not establish that a drop rate is sensible or that the runtime recognises a feature name. Those are separate concerns for the consuming app.

Use yaml when the runtime already reads YAML. Syntax highlighting follows the field's language, and its language pack loads only when a field uses it. The Require valid JSON option is for JSON fields.

A website: an editor-controlled verification tag

For a website, the code might be a verification tag in the head or an analytics loader at the end of the body.

Create an HTML code field named embed. An editor can enter a verification tag:

<meta name="example-site-verification" content="verification-token">

In an Astro page, render the string into the head. Here, site is the content object your page has fetched:

---
const { site } = Astro.props;
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <Fragment set:html={site.embed ?? ""} />
  </head>
  <body>
    <slot />
  </body>
</html>

The same approach can place an editor-maintained script near the closing body tag.

On a static site, the change goes live after the next build, not instantly. Adding the field itself needs no rebuild, restart or deploy of Shapio. Models change live in the admin while Shapio runs. The website's build is a separate step.

What the API sees

In a schema file, an HTML code field uses:

{
  "type": "code",
  "settings": {
    "language": "html"
  }
}

Language is set once per field, not per entry. The options are plain, html, css, javascript, json, yaml and markdown.

REST returns the string. GraphQL returns String, with a field description ending in Code: html. OpenAPI adds x-shapio-language and, for HTML, contentMediaType: text/html. Generated TypeScript keeps the language in its doc comment:

/** Embed (Code: html) */
embed: string | null;

Code fields cannot be unique, filterable or sortable. Changing long text to code preserves every value, but the planner flags the change as breaking because filtering is lost. Confirm it in the change set or use --allow-breaking with shapio schema apply. Changing code back to text is not breaking.

Use a code field when the content belongs in a code editor and a client consumes its syntax. Keep prices and titles in normal fields. Let the writer or editor maintain the source, let Shapio preserve its bytes, and let the game, app or website interpret it.

I didn't build redirects into my CMS

Wed, 07 Oct 2026 00:00:00 GMT

The roadmap card

Redirects were a Now item on the shapio.dev roadmap. The card promised redirects “managed per site in the admin and written into your host's redirect file at build time”. I decided not to build that feature.

Shapio is an open-source, self-hosted headless CMS. Its content model is data in the database, so you can change a type in the admin while production keeps running. The REST and GraphQL APIs serve a new field on the next request, without a rebuild, restart or deploy.

Redirects are website plumbing. The CMS does not need to know what a redirect is. It needs to store the entries, control who can read them and deliver them to the build.

What Strapi users add with a community plugin, and WordPress users with a plugin that has millions of installs, is a content type and a build step here. The existing model and delivery API can carry the data.

Make the type

In the admin, create a content type named redirect (its plural API ID is redirects). Give it these fields:

from: short text, required, unique.
to: short text, required.
type: choice with the values permanent (label 301) and temporary (label 302), default permanent. Choice values must be GraphQL names, so they cannot be numbers. The field cannot be called status, because every entry already has a system field with that name.
enabled: boolean, default true.
note: long text.

That takes two minutes, live, with no deploy. Give the site's build token, through its delivery role, read access to the type. In the starter, that role is “Starter site (delivery)”.

Only published redirects reach the build, because the delivery API serves published content only. On an instance with several sites, the type belongs to the site that uses it.

Write the file at build time

The Astro starter already writes a _headers file at build time for Cloudflare Pages and Netlify. Put _redirects beside it in dist. Both hosts read that file, with one rule per line in the form from to status.

In the Astro starter, src/lib/shapio.ts has a listAll helper that reads a collection page by page at the build's pinned snapshot (one delivery page holds at most 100 entries). It always asks for SEO fields with the site's defaults filled in, which Shapio refuses for a type without an SEO field. Export it, and move its ...query line below seo: 'resolved' so a caller can override that:

export const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T[]> => {
  // …
    const result = await shapio().delivery.list<T>(routeKey, {
      richText: 'html',
      seo: 'resolved',
      ...query,
      snapshot,
      page,
      pageSize: PAGE_SIZE,
    });

Then add a page that writes the file. Astro turns src/pages/redirects.txt.ts into dist/redirects.txt, and a rename at the end of the build script makes it _redirects:

// src/pages/redirects.txt.ts
import { listAll } from '../lib/shapio.js';

type Redirect = { from: string; to: string; type: 'permanent' | 'temporary'; enabled: boolean };

const CODE = { permanent: 301, temporary: 302 } as const;

export const GET = async () => {
  const rules = await listAll<Redirect>('redirects', { seo: 'raw' });
  const lines = rules.filter((r) => r.enabled).map((r) => `${r.from} ${r.to} ${CODE[r.type]}`);
  return new Response(lines.join('\n') + '\n');
};

"build": "ASTRO_TELEMETRY_DISABLED=1 astro build && mv dist/redirects.txt dist/_redirects"

The pinned snapshot matters for the same reason it matters for the pages. Shapio's change sets and publication snapshots let schema and content ship together, and a build can pin a snapshot so every page sees one consistent moment. The redirect list should come from that moment too.

There is no separate publishing path to add. With a deployment connection, publishing a redirect rebuilds the site the same way publishing a post does.

Next.js and SvelteKit

For Next.js, the same list goes into redirects() in next.config, which is already async. Map permanent to statusCode: 301 and temporary to statusCode: 302; Next's own permanent: true and false send 308 and 307. Next reads redirects() at build time, and the Next starter revalidates on publish instead of rebuilding, so a new redirect goes live with the next deploy. For SvelteKit, write build/_redirects the same way as Astro.

The missing prompt

There is an honest gap: the one-click “your slug changed, add a redirect” prompt. That needs the CMS to notice that a slug moved on a published entry. Creating a type and writing a file does not supply that prompt.

That is the one piece that may belong in core later, as a generic "field changed" event, not as a redirects feature.

A redirect is a content type and a build step.

The test for core

I now apply this test to roadmap items: does the work improve the model or the API for any consumer? That consumer might be a site, an app, a game or a script. Or does the work only help a website on one host?

Core takes the first. Starters take the second. Redirect file generation goes in the starter.

See saved drafts on your development server

Tue, 06 Oct 2026 00:00:00 GMT

Drafts mode lets your development server render the content saved in Shapio, including entries never published. You save in the admin and reload the page on your machine. Publish stays a production action: it updates your live site.

Before you start

You need a running Shapio with an owner account. Choose the starter for the framework you use: Next.js, Astro, or SvelteKit. All three render the same blog and support drafts mode.

You also need a delivery token whose role grants read on the site's models and Read drafts. The starter seed creates that role and token for you. Keep the dev token in your local environment. Never put it in production.

Step 1: Create your starter

npx create-shapio my-site --site next      # or astro, sveltekit
cd my-site

This creates the framework app and the blog's model files in shapio/. Keep --site: without it, create-shapio creates a Shapio CMS project instead.

Step 2: Seed the content and dev token

SHAPIO_URL=http://localhost:4300 SHAPIO_ADMIN_EMAIL=you@example.com SHAPIO_ADMIN_PASSWORD='…' npm run seed

The seed applies models, creates and publishes content in English and French, and leaves one article as a draft. It writes .env, including SHAPIO_DEV_DELIVERY_TOKEN for the second delivery role, <site> dev, which may read drafts.

The seed is idempotent: running it again resets the content. It signs in with a temporary admin API token and revokes that token when it ends.

Step 3: Check the delivery role

The seed already did this. If you create the role yourself, open Network → Roles → New role, choose kind Delivery, grant read on the site's models, and enable Read drafts. Then create a token bound to that role in Settings → API tokens; the tokens list marks it with a Drafts chip.

Read drafts covers every model the role reads. It adds no model of its own, so you still need the model grants. Delivery tokens can only read, whatever their role says.

Step 4: Turn on drafts locally

SHAPIO_DRAFTS=true

Set this in your local .env; the starter reads saved drafts with SHAPIO_DEV_DELIVERY_TOKEN when it is set, otherwise with SHAPIO_DELIVERY_TOKEN. Every page carries a Drafts badge in its corner, and drafts mode pins no snapshot.

Every read is fresh. Under Next.js, draft reads are never cached or tagged, and the Next starter's /api/revalidate route does nothing. A local build can also read drafts with this setting. Never set SHAPIO_DRAFTS or put the dev token in a production environment.

Publishing updates your live site, so it is not how you check a change.

Step 5: Start the development server

npm run dev

Save a change in the admin, then reload the page on your machine. The saved change should appear, with the Drafts badge still visible.

Drafts include autosaves and may not pass validation yet. A required field can be empty, so render drafts defensively. Drafts mode covers the whole site for developers; the admin's Preview pane is for previewing one entry, and the starter's /preview/ page is unchanged.

Step 6: Check a draft read directly

In a shell with SHAPIO_URL and SHAPIO_DEV_DELIVERY_TOKEN set to the values in .env:

curl -H "Authorization: Bearer $SHAPIO_DEV_DELIVERY_TOKEN" \
  "$SHAPIO_URL/api/content/articles?publicationState=draft&populate=author"

The REST request asks for drafts with publicationState=draft and returns each entry's saved draft in the delivery shape, including entries never published. Look for meta.publicationState: "draft"; relation targets and populate follow drafts too, within the models your role may read.

For GraphQL, request publicationState: DRAFT. With @shapio/client, use drafts: true on createClient; with @shapio/local, use it on createLocalClient. The server requires Read drafts and the site must ask for drafts. Anonymous callers and end-user accounts can never read them.

Check it worked

Check a saved edit after reloading and confirm the page shows the Drafts badge. The direct REST response should identify its publication state as draft and carry Cache-Control: private, no-store, so no cache keeps it.

Leave Publish for production. Published reads are unaffected; drafts mode gives your machine access to saved content without publishing it.

When it goes wrong

If the token lacks Read drafts, the server returns 403 DRAFTS_FORBIDDEN with a message naming the grant. The starter's first read fails: a build stops, or the dev server shows the message on its error page. It never falls back to published content. Check that the selected token belongs to the delivery role with Read drafts and the required model grants.

A draft cannot be pinned. Combining publicationState=draft with snapshot returns a 400. Check that your direct draft request does not also request a snapshot.

Drafts had to be a permission, not a flag

Mon, 05 Oct 2026 00:00:00 GMT

Save, refresh, nothing

I was editing my own site's content in the Shapio admin with the site's development server running. I saved a change, refreshed the page, and nothing changed. I asked whether I had to publish too.

The answer was yes. The site reads published content only, by design. Drafts never leak to the public API, so saving a draft had done exactly what it was supposed to do.

Publish meant production

My objection was simple: Publish is a production action. On my site, publishing fires a Cloudflare Pages rebuild of the live site. Using that button to test content on a development server would also ship it.

That left a gap between saving content and seeing it in the development site. Shapio already had per-entry preview tokens for the admin's Preview pane. Those covered one entry for one hour.

A per-entry preview did not give the development server access to saved drafts across the site. I wanted to render those drafts while keeping Publish as the action that changes production. That distinction belongs in the product, even when the person editing the content also runs the site.

The tempting flag

The wrong fix would have been a site setting: SHAPIO_DRAFTS=true. Set it, ask the server for drafts, and have the server hand them over. It would have answered my immediate complaint.

It would also have made any site with that flag able to read any draft. The rule that public delivery never leaks drafts would then depend on a configuration value on someone else's machine. That is an unacceptable place to enforce access.

The site can decide which content it wants to request. The server has to decide which content the caller is allowed to receive. Combining those decisions into one flag makes the access rule too easy to mistake for a development convenience.

Two safeguards

The fix shipped on October 5, 2026, in release 0.5.1. Delivery roles gained a new permission, "Read drafts". That permission covers every model the role can read.

The delivery API accepts ?publicationState=draft, and GraphQL accepts publicationState: DRAFT. A token without the grant gets DRAFTS_FORBIDDEN. Anonymous callers and end-user accounts can never read drafts.

That gives us two required safeguards: the grant on the server and the request from the site. The token must be allowed to read drafts, and the site must ask for them. A production token has no grant, so the flag alone shows nothing.

The starters use SHAPIO_DRAFTS=true to turn on draft reads with a separate development token created by the seed. They also show a "Drafts" badge on every page. The development token is never put in a production environment.

The flag still exists, but it now expresses what the site is asking to render. It cannot grant itself access. Configuration selects the mode, while the server enforces the permission.

Draft responses also carry Cache-Control: private, no-store. The client has a drafts: true option, and under Next.js those reads are never cached or tagged. Being allowed to read a draft never makes it cacheable.

Relations exposed the mistake

The first draft of the plan had a per-model grant. Review caught the problem with it: related entries were only checked for plain read permission, so a token allowed drafts of posts could have pulled draft authors through a relation.

The grant became token-wide, covering every model the role reads. A caller's ability to read drafts therefore applies across those models, including the related entries.

Plan review caught several problems like it before any code was written, and the change shipped in one release. The relation catch is the one I keep coming back to. It shows why the permission needs to cover the content a request can reach, rather than just the entry where the request starts.

Who enforces it

If the server cannot refuse it, it is not a permission, it is a hope.

That is my test for where a thing belongs: who enforces it. A site can ask for drafts with a flag. The server must be able to say no.

Move a Strapi 5 project to Shapio with the importer

Sun, 04 Oct 2026 00:00:00 GMT

The importer turns Strapi content types into models, documents into entries, and uploads into media library assets. Every entry is created as a draft, and the ones that were published in Strapi are collected into a change set you review and ship.

Nothing goes live by itself.

Before you start

You need a Strapi 5 project and a running Shapio instance. Only Strapi 5 exports are supported.

Open /admin/ on the instance. If no admin account exists yet, Setup asks for your name, email and a password of at least 12 characters, entered twice. Do it right after the first start: until then, anyone who can reach the server can claim it.

Create the token the import runs with. In the admin, open Settings → API tokens, choose New token, give it a name, pick the Admin role and choose Create. The token is shown only once: copy it.

export SHAPIO_URL=https://cms.example.com
export SHAPIO_TOKEN="<the token>"

Run every npx shapio command below in your Shapio project (the one npm install @shapio/cms or create-shapio set up), where npx shapio finds the CLI. Anywhere else, including inside the Strapi project, use npx -p @shapio/cms shapio instead.

If your Strapi content is localized, add the same locales in Settings → Locales (Add locale, then a code such as fr and a name). The import refuses to start while one is missing.

Step 1: Export your Strapi project

npx strapi export --file my-export --key "<the key>"

Run this in the Strapi project, then move the file next to your Shapio project. It writes my-export.tar.gz.enc, encrypted with the key. Keep the key, and once you have planned the import, leave the export file where it is until the import is done: the map step checks that the file has not changed.

Step 2: Plan the import

npx shapio import strapi my-export.tar.gz.enc --plan ./import --key "<the key>"

The plan runs offline and sends nothing anywhere. It unpacks the export into ./import/source, so the key is needed only once, writes the proposed models into ./import/schema and prints every model with its entry counts.

Collection type / single type becomes collection / single type, API ID from the singular name, plural kept
Component becomes component, API ID from its name
uid becomes uid (unique)
float becomes number
enumeration becomes enum, or string when the values are not valid API names
blocks, richtext (Markdown) becomes rich text
media becomes media, single or multiple, allowed kinds kept
relation becomes relation (one or many) on the owning side

Reserved names get a suffix, and the plan lists each one: Strapi's example components shared.media and shared.rich-text become mediaItem and richTextItem. Every planned model has draft and publish on.

Validation rules are not carried over. Users, roles, API tokens, plugin content types, configuration and review workflows are not imported.

Step 3: Review and apply the schema

npx shapio schema apply --dir ./import/schema --lock ./import/schema-lock.json

Before applying, you can rename API IDs and labels or delete fields. Entries follow stable IDs, so renames are fine.

The models belong to the primary site, so your admin token works without --site. To import into another site, plan with --site <key>. To share the models with all sites, plan with --shared and apply with a network admin token.

Step 4: Import media and content

npx shapio import strapi --map ./import

This uploads every upload file from the archive with its alternative text and caption, creates every document as a draft (referenced entries first), opens the change set and prints its link. It ends with a summary like this one:

Media: 11/11 uploaded. Entries: 18/18 created (3 stay drafts: they were not published in Strapi).

A locale published in Strapi goes into the change set, and a draft-only locale stays a draft. The owning side of a relation is imported; you answer the inverse direction with a filter on the owning field.

Step 5: Review and ship the change set

https://cms.example.com/admin/s/default/changes/<id>

Open the link the map step printed (also under Changes in the admin). Each item shows its locale, the Publish action and its fields. Choose Ship, then Ship again in the confirmation. Everything goes live together as one snapshot, and the page shows "Shipped. Live as v1".

Check it worked

curl -H "Authorization: Bearer $SHAPIO_TOKEN" "$SHAPIO_URL/api/content/articles?populate=author"

Swap in the plural API ID of one of your models. Only entries that were published in Strapi come back, with their relations filled in. Add &locale=fr to read another locale.

Check the rich text. Blocks map directly, with underline and strike-through dropped. In Markdown, strike-through loses its mark and raw HTML is unwrapped.

When it goes wrong

schema apply refuses with FORBIDDEN_SCOPE if you planned with --shared and the token belongs to one site. Use a network admin token, or plan again without --shared.

--map refuses until the models exist, and names the missing ones and the apply command to run. It also refuses while a locale is missing, and names it: add it in Settings → Locales and run --map again.

An existing model with the same API ID stops schema apply. Rename the planned model's API ID and plural API ID in its file, and any colliding component, then apply.

Re-running --map skips finished work and retries what failed. It refuses if the export file changed since it was planned. --plan never overwrites an import that has started: plan into a new directory to start over.

A Strapi 4 export is refused. Upgrade the project with npx @strapi/upgrade major, then export again.

A set holds at most 2,000 items. A larger import opens numbered sets, "Import from Strapi (1/2)" and so on, which you ship one after another.

The rate limit is waited out automatically, but while a large --map runs, the admin opened from the same address can answer RATE_LIMITED for up to a minute.

Deploy a Shapio site to Cloudflare Pages and rebuild on publish

Sat, 03 Oct 2026 00:00:00 GMT

Cloudflare builds your site from Git, and Shapio starts each build through a deploy hook. Shapio follows the build through Cloudflare's API so you can see whether published content reached the website.

Publish once and the deploy hook does the rest.

Before you start

You need a running Shapio with an owner account, installed through npm or Docker. Your Shapio must be reachable from the internet for Cloudflare to read content.

This guide uses the Astro starter, which produces static HTML. Next.js uses on-demand revalidation, while SvelteKit uses a full rebuild started by a deployment connection.

Step 1: Create and seed your site

npx create-shapio my-site --site astro
cd my-site

This creates a standalone Astro project with the blog's model files in shapio/. Seed it against your running Shapio, using your address and owner credentials:

SHAPIO_URL=https://cms.example.com SHAPIO_ADMIN_EMAIL=you@example.com SHAPIO_ADMIN_PASSWORD='…' npm run seed

The seed applies the models, uploads placeholder images, creates English and French content, and writes SHAPIO_URL and SHAPIO_DELIVERY_TOKEN to .env. Open the admin: Content shows pages and articles, Models shows the models, and Media shows images.

Running the seed again resets the content; its temporary admin API token is revoked when it finishes. It also creates a <site> dev token, written as SHAPIO_DEV_DELIVERY_TOKEN, that can read drafts and must never go to production.

Step 2: Build and inspect locally

npm run build
npm run preview

The preview serves dist/ and prints its address, http://localhost:4321/ unless that port is taken. The home page redirects to /en/, and the language switch leads to /fr/.

Each build reads the current publication snapshot once and pins it, sending it with every request as ?snapshot=N. Content published during the build waits for the next build; /build.json shows the built snapshot.

Step 3: Connect Cloudflare Pages to Git

Push my-site to your own GitHub or GitLab repository, then select that repository in Cloudflare:

Workers & Pages → Create → Pages → Connect to Git
Framework preset: None
Build command: npm run build
Build output directory: dist
Root directory: leave empty

The Astro preset works too; both give npm run build and dist. In Production environment variables, set NODE_VERSION to 24 and SHAPIO_URL to your Shapio's address, for example https://cms.example.com. Set SHAPIO_DELIVERY_TOKEN as a secret, using the token the seed wrote to .env or one from Settings → API tokens with a delivery role that reads page, article, author and siteSettings.

Never set SHAPIO_DRAFTS or SHAPIO_DEV_DELIVERY_TOKEN in production. Click Save and Deploy: the first build runs and the site becomes live at https://<project>.pages.dev.

After the first build, turn on Settings → Builds → Build cache. The starter re-renders only the pages whose content changed and restores the rest from the previous build, and that needs the cache to survive between builds. Without it, every build is a full one.

Step 4: Create the hook and API token

Workers & Pages → your Pages project → Settings → Builds → Deploy hooks → Add deploy hook
My Profile → API Tokens → Create Token → Custom token

Create the hook for the production branch and copy its URL. Give the custom token Account → Cloudflare Pages → Read, limited to your account, and copy the token.

Note the project name and account ID. You can find the account ID in the Workers & Pages overview's right-hand column or the 32-character hex string in the dashboard URL.

Step 5: Add the deployment connection

Publishing → Deployments → New connection → Cloudflare Pages

Enter the account ID, project name, deploy hook URL and API token, then select On publish and Manual. Test connection should pass: it checks that the token can read the project without starting a build.

You can enter the API token as ${ENV:SHAPIO_SECRET_CF_PAGES_TOKEN} instead. Set that variable for Shapio's API and any dedicated worker; Shapio stores only the variable name and reads its value when needed.

With On publish selected, every publish starts a build. Bursts are coalesced, so ten publishes in a minute start one build.

Step 6: Set up draft preview

Set the connection's preview URL template:

https://<project>.pages.dev/preview/?model={modelKey}&id={entryId}&locale={locale}#token={token}

Add https://<project>.pages.dev to Shapio's CORS_ORIGINS and restart Shapio after changing it. The entry's Preview opens the draft beside the document; clicking its title or body focuses that field.

Check it worked

Publish something. The connection's run should move through triggered → building → deployed, with Cloudflare's build log link and the snapshot it was started for. Open the site and check the change.

A Pages deploy hook cannot pass parameters, so the build pins the snapshot current when it starts.

When it goes wrong

If a build is already queued for the branch, Cloudflare answers the hook with HTTP 304. Shapio follows that queued build and reports its result.

A provider that stops answering shows unknown. Shapio does not invent completion status.

A wrong SHAPIO_DELIVERY_TOKEN makes the build fail reading content with 401. Shapio shows failed, the reason and the log link, while the content stays published. Restore the right token and Retry the run. Check that it deploys and the site shows the change.

Schema as code: pull your content model into git and apply it live

Fri, 02 Oct 2026 00:00:00 GMT

Shapio syncs the models in an instance with JSON files so you can pull, edit and apply your content model. You can review changes in git while every environment, including production, remains editable in the admin by default (a read-only lock exists, and it is opt-in).

Before you start

You need an instance and an admin API token from Settings → API tokens. All shapio schema commands talk to the instance over HTTP, never to its database. Supply --url and --token, or set SHAPIO_URL and SHAPIO_TOKEN. Run the commands in your Shapio project (the one npm install @shapio/cms or create-shapio set up), where npx shapio finds the CLI; anywhere else, use npx -p @shapio/cms shapio.

Choose a local or staging instance for modelling. Schema sync moves models only. To move or back up content, use shapio export and shapio import.

Git mirrors production; it never locks it.

Step 1: Pull the schema

export SHAPIO_URL=https://cms.example.com SHAPIO_TOKEN=shp_…
npx shapio schema pull

Pull writes one canonical JSON file per model and component, with sorted keys, stable IDs and every default spelled out. It also writes .shapio/schema-lock.json, which records each definition's version, hash and site, so commit both the schema files and the lock file.

Pulled 8 definition(s) of site "default" at schema version 12 into schema

Step 2: Check the files and site

schema/
  models/                 shared with all sites
  components/
  sites/
    blog/models/          the blog site's own
    shop/models/          the shop site's own
.shapio/schema-lock.json  every definition's version, hash and site, and the sites the tree covers

Shared definitions go in schema/models/<apiKey>.json and schema/components/<apiKey>.json, while a site's own definitions go in schema/sites/<siteKey>/models/ and schema/sites/<siteKey>/components/. Commands work on one site's view: --site <key> or SHAPIO_SITE selects it, otherwise they use the token's site, then the primary site.

Step 3: Edit and review in git

Edit models in your local or staging admin. In the builder, Review in a change set queues the edit and Ship now ships it at once. Then pull, commit and open a pull request, or edit the JSON files directly. A new file may omit IDs: the instance assigns them on apply and rewrites the file in canonical form.

Step 4: Preview and apply to production

npx shapio schema diff     # what apply would do; changes nothing
npx shapio schema apply

With SHAPIO_URL and SHAPIO_TOKEN pointing to production, diff previews the changes and apply runs the same change planner as the admin, with checks, background index builds and atomic activation, without a restart. Apply waits for activation, then updates the lock file and applied files; --no-wait returns at once, while --wait-timeout <seconds> changes the default 600-second wait.

model article: update
    + field subtitle
Applied 1 definition(s) at schema version 13.

Step 5: Choose how schema and content ship

CLI apply activates each changed definition directly and does not create a change set. To ship schema and content together, use the admin instead. Develop → Schema saves edited files as drafts in a change set, after the same three-way check, and shipping that set publishes the schema and its content items as one snapshot. In the builder, Ship now ships a single edit as a one-item change set.

Check it worked

Run npx shapio schema diff again: it reports nothing to apply. Commit the updated lock file.

How apply decides

Apply compares the base in the lock file, your file and the target's active definition for each model. If your file is unchanged, it skips the model and keeps live changes made since your pull. If only your file changed, it applies with the target's current version as a guard. If both changed, it refuses and shows both sides. A file identical to the target is already applied and skipped.

The reverse workflow is valid too: edit production, then pull and reconcile. For automatic write-back, add a GitHub connection under Publishing → Deployments. After schema changes, it commits the canonical files and lock file, or opens a pull request from shapio/schema-sync.

Check Develop → Snapshots for the schema version recorded with a snapshot. Metadata-only changes do not take a snapshot; conversions of stored values do. Older snapshots use the current schema, and restoring content does not roll back the schema.

When it goes wrong

A conflict refuses the whole apply and writes nothing. The refusal looks like this:

SCHEMA_SYNC_CONFLICT: The target schema changed since your last pull for some definitions you also changed. Pull, reconcile and apply again.

Commit your files, then run:

npx shapio schema pull --force

This overwrites files with the target's definitions and records the new base. Use git diff to bring your changes back on top, commit and apply again. Pull also refuses unapplied local edits unless you use --force. After upgrading Shapio, pull again: a new version can add default properties to definitions, which changes their hashes.

Breaking changes need --allow-breaking; destructive conversions need --allow-destructive. Deleting a file does nothing on the target without --prune, which still refuses deletion if the target definition changed.

For several sites, LOCK_SITE_MISMATCH means you must pull the selected site first. SCOPE_MISMATCH means the file's folder disagrees with the instance: pull its layout. Changed shared definitions require schema permission on every site; FORBIDDEN_SCOPE lists refused definitions and nothing applies. Check that the selected site's tree and shared-definition permissions match the target before applying again.

What's left of the JAMstack

Thu, 01 Oct 2026 00:00:00 GMT

What the word meant

JAMstack stood for JavaScript, APIs and Markup. Netlify's founders coined it around 2016. The proposal was concrete: pre-render a site to static files, serve those files from a CDN, and use browser JavaScript and third-party APIs for anything dynamic.

Gatsby, Hugo, Jekyll, Eleventy and early Next.js static export belonged in that picture. Netlify and Vercel built businesses on it. Content came from Markdown files in the repository or from an API, and the API side is where headless CMSs grew up.

What it got right

Static files are fast, cheap and hard to hack. A CDN is a better front door than a PHP box. Those remain good reasons to build a site this way.

The build also gave you a reproducible artifact. You could pin it and roll it back. I put more value on that property than on whether a framework still fits an old acronym.

A build is a reproducible artifact.

The content API mattered just as much. Content could be the source for the site without being a database joined to templates.

Choosing an API for content does not settle whether every page should be static. It gives you a source to work from. Content delivery and page rendering are separate decisions.

How it went wrong

Build times grew with content. A ten-thousand-page site rebuilding for a typo is a concrete problem, whatever you call the architecture. A tidy deployment model doesn't excuse that cost.

Every dynamic need became a function or a client-side fetch. Incremental regeneration and on-demand rendering were bolted on. Those additions made the original definition less useful as a guide to what a site actually does.

By now, every major framework renders on the server again. Next.js has the app router, Astro has server islands and on-demand pages, and SvelteKit and React Router (formerly Remix) are part of that server-rendered picture. Netlify itself stopped leading with the word JAMstack.

The term is dead; the useful parts have become standard practice. Describe which pages are built ahead of time, which need server rendering, and where their content comes from. That tells me more than the label does.

What's left

Keep the build as an artifact you can pin and roll back. Keep static output wherever content changes slower than requests arrive. A long build is a reason to examine the build, not to discard static files everywhere else.

Keep a content API as the source. I don't want the choice of templates to dictate where content lives. That preference doesn't mean every site needs a headless CMS.

Rebuilding on publish is the other part worth keeping, with one correction. Publication is the point at which the content changes for readers, so that is the moment to produce pages. That part the old pattern got right.

What it got wrong was the scope. A typo rebuilt the whole site, and that is what people walked away from. That part is fixable now. Astro can restore every page whose content and code did not change and render only the rest, and a cached server-rendered site, like Next.js with cache tags, can expire just the pages a publish touched.

The dynamic parts can still be dynamic. Another part needing server rendering is no reason to abandon static output for content that suits it. Make that decision around the content and the request.

Where Shapio fits

Shapio is built for the parts of this that held up. A build pins one publication snapshot (?snapshot=N), so every page in it shows the same moment of content and schema. With a deployment connection, a publish fires the deploy hook and Shapio follows the build until it finishes. The site you are reading is built that way.

The scope problem is handled in the starters. The Astro starter keys every page on the content it renders, so a publish re-renders the pages that changed and restores the rest from the previous build, as long as the host keeps its build cache. The Next.js starter caches its reads by tag, and a publish expires only the tags of the content that changed.

The CMS itself never needs a deploy. Content types are data in the database: change one in the admin and the REST and GraphQL APIs serve the new field on the next request. Showing that field on the site is a change to the site's code, which ships with the site's next deploy.

For the parts that must be dynamic, the same content is on the API, and in a Next.js app @shapio/local serves it in-process. Build the static pages on publish, and render on request only what needs it.

Why headless

Wed, 30 Sep 2026 00:00:00 GMT

What the head was

A headless CMS stores and serves content through an API and leaves rendering to whatever front end you build. The head was the theme and the templates, the part that turned stored content into a page. Remove that part and you have content available to a separate application.

Content is data

My first reason is that content is data. An article has a title, a body, and whatever other fields its model defines. A page is a rendering of that article. Treating the article as data gives you a better starting point than treating its current page as the thing you are storing.

The same source can feed a site, an app, a feed, or a script. You do not have to enter the content again for each destination. Each consumer can take the fields it needs and decide what to do with them.

There is still work in each consumer. An API does not design your app or write your feed. That work belongs with the consumer, where the requirements for its output are clear.

The front end is yours

My second reason is control over rendering. I want to choose the framework, the host, and how the front end produces its pages. I do not want a theme system making those decisions for me.

If you have worked with WordPress, you know what a theme is responsible for. Headless moves that responsibility into the front end you build. You own the templates because they are part of your application.

It also means the choice is yours to maintain. Choosing your own front end includes building it and taking responsibility for it. That is a reasonable trade when a team actually wants that control.

The schema is the contract

My third reason is the schema. The content model defines the API, and types follow from that model. The front end and the content team can agree on a shape instead of agreeing only on a page.

That changes what I want to discuss when modelling content. We need to agree on which fields belong to a type and which parts of the content should be shared. Those decisions describe the data the front end will receive.

The schema is the contract.

The front end depends on a shape, and changes to that shape need attention. Moving rendering out of the CMS does not remove the need for agreement.

A service with an API

A CMS should behave like any other service with an API. Your pages do not run through the CMS's own code, whether that is WordPress's PHP or anything else, and the site is not assembled from plugins that each bring their own data shapes, update cycle and attack surface.

The CMS stores and serves content, and the front end renders it. When something breaks, it is clear which side broke.

When I would keep the head

For a brochure site with an editor who wants to drag things around a page and never touch code, and no developer building the site, I would keep the head. Building a separate front end adds a job that editor did not ask for. I would choose a tool that fits the way they want to work.

For a small shop where the storefront and the catalogue are one product and nobody wants to build a front end, Shopify or WooCommerce handles it end to end. Headless pays off when the catalogue feeds more than one storefront, which is why a headless e-commerce layer is on Shapio's roadmap.

The same goes for any team with no developer. Headless gives you a front end to build. If nobody wants to build one, use the thing with the head.

Changing the contract

The usual headless cost arrives when the model changes. Strapi disables its content-type builder in production, and Payload defines fields in TypeScript. Model changes can mean code, commits, and a deploy.

Shapio's position is that the model should be data too. Change a type in the admin while it runs in production, and the REST and GraphQL APIs serve the new field on the next request. There is no rebuild, restart, or deploy for that model change.

Schema and content ship together in a change set, recorded as a publication snapshot that a build can pin. Every page in the build then sees one consistent moment. That is the contract I want to build against.