See saved drafts on your development server

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 [email protected] 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.