Snapshot mode

Snapshot mode lets the Content Island API client serve all of its read methods from a local file instead of calling the API on every request. A project’s full content is exported once as a single JSON document — the snapshot (transferred gzip-compressed from the export endpoint, then stored as plain JSON on disk) — and the client reads from it with drop-in parity to the live API: the same methods, the same shapes, the same results.

Snapshot mode is designed for applications that need to read content frequently without making an API request on every operation.

Export the project once, keep the snapshot locally, and resolve all read operations directly from that snapshot. This reduces latency, eliminates unnecessary API traffic, and makes applications more resilient to network issues, rate limits, or temporary API outages.

Static site generation is a natural fit, but the same approach also works for SSR, ISR, server functions, background jobs, and other server-side workloads.

Note

Snapshot mode changes where reads come from, not what they return. Code written against the live API keeps working unchanged — you only switch the source of the data.

Caution

A snapshot is a point-in-time copy: loaded once per process and immutable for that process’s lifetime. To serve newer content you re-export and redeploy (or restart the process). When you need always-live content, use 'api' mode.

Choosing a mode

The client operates in one of two modes:

Mode	Reads come from	Default
'api'	The live Content Island REST API.	yes
'snapshot'	A local snapshot file (snapshotPath).	—

You set the mode when you create the client:

import { createClient } from '@content-island/api-client';

const client = createClient({
  accessToken: 'YOUR_ACCESS_TOKEN',
  mode: 'snapshot',
});

In 'snapshot' mode reads are served from the local snapshot file with no request to the API and with drop-in parity to the live results. When mode is omitted, the client defaults to 'api' and behaves exactly as it always has.

The snapshot file

In snapshot mode the client reads from a snapshot file on disk. You point to it with the optional snapshotPath option:

const client = createClient({
  accessToken: 'YOUR_ACCESS_TOKEN',
  mode: 'snapshot',
  snapshotPath: './content-island-snapshot.json',
});

snapshotPath is optional and defaults to './content-island-snapshot.json'. It is not required: omitting it simply uses the default path. An error is raised only when the file at that path is missing, unreadable or invalid — never just because the option was left out.

Caution

snapshotPath is resolved relative to the current working directory (cwd) of the process, not relative to the source file that calls createClient. During a typical build the cwd is your project root, so the default works out of the box. In SSR / serverless contexts (server-side rendering or serverless functions) the working directory is often unpredictable — pass an absolute path there to avoid surprises.

Where the mode is set

The mode lives in two places:

• Client level — the mode option on createClient sets the default for all reads.

• Per read — the five read methods accept a mode inside the query object, affecting only that one call:

  • getContentList
  • getContent
  • getRawContentList
  • getRawContent
  • getContentListSize

// The client reads from the API by default;
// this one read is served from the snapshot:
const client = createClient({
  accessToken: 'YOUR_ACCESS_TOKEN',
  snapshotPath: './content-island-snapshot.json',
});

const posts = await client.getContentList({
  contentType: 'post',
  mode: 'snapshot', // this read only
});

Note

The client-level mode is your app-wide default strategy — for example, run primarily in 'snapshot' mode and resolve most reads locally. When a single operation needs different behaviour, override mode per read: switch one query to 'api' (or vice versa) without affecting the rest of the app.

getProject does run in snapshot mode — it’s served from the snapshot’s project object (languages included). It simply takes no query-params object, so there is no per-read mode for it: it always follows the client-level mode. To inspect the on-disk snapshot without loading the project, use getSnapshotInfo.

Note

If a read sets its own mode, it takes priority over the client’s mode. The effective mode of any read resolves as effective mode = per-query mode ?? client-level mode ?? 'api': the per-read mode wins, then the client-level mode, then the 'api' default.

Note

mode (and onRelatedContentMeta, below) are client-only options. In api mode they are never serialized into the request query string sent to the API — they only steer how the client resolves the call.

onRelatedContentMeta

onRelatedContentMeta is an optional per-query callback that reports how the related-content resolution went. It runs on the same five read methods and has the signature:

onRelatedContentMeta: ({ resolvedDepth, partial }) => void;

It is invoked exactly once per call:

• resolvedDepth — how deep the related-content resolution actually went.
• partial — true when a depth or resolution-budget cap left part of the related-content graph unresolved.

The callback works in both modes, and for the same data and query it reports identical values:

• In api mode, the values come from the X-Related-Content-Resolved-Depth and X-Related-Content-Partial response headers (an absent partial header is treated as false).
• In snapshot mode, the values come from the local breadth-first resolution over the snapshot.

const list = await client.getContentList({
  contentType: 'post',
  includeRelatedContent: 'all',
  onRelatedContentMeta: ({ resolvedDepth, partial }) => {
    console.log({ resolvedDepth, partial });
  },
});

When onRelatedContentMeta is omitted, behaviour and return shapes are unchanged. Like mode, it is a client-only option and is never serialized to the query string.

Writes are not available in snapshot mode

A snapshot-mode client serves reads only. A snapshot is a frozen, read-only copy of your content, so there is nothing to write to. Every write and schema-management method rejects with an ApiClientError whose code is SNAPSHOT_MODE, and it performs no network call — the rejection happens locally, before any request would be made:

• createContent
• publishContent
• updateContentFieldValue
• uploadMedia
• createModel
• updateModel
• deleteModel
• createEnum
• updateEnum
• deleteEnum

import { createClient, ApiClientError } from '@content-island/api-client';

const client = createClient({
  accessToken: 'YOUR_ACCESS_TOKEN',
  mode: 'snapshot',
});

try {
  await client.createContent(/* … */);
} catch (error) {
  if (error instanceof ApiClientError && error.code === 'SNAPSHOT_MODE') {
    // Writes are rejected in snapshot mode — no request was sent.
  }
}

Caution

Unlike reads, writes have no per-query override. On a snapshot-mode client they always reject — you cannot opt a single write back onto the API the way you can flip a single read with a per-query mode.

If you need to read from a snapshot and also write, create a second, separate client in 'api' mode for the writes, authenticated with a Write Token:

import { createClient } from '@content-island/api-client';

// Reader: serves reads from the local snapshot.
const reader = createClient({
  accessToken: 'YOUR_READ_TOKEN',
  mode: 'snapshot',
});

// Writer: a separate api-mode client for writes.
const writer = createClient({
  accessToken: 'YOUR_WRITE_TOKEN',
  // mode defaults to 'api'
});

const posts = await reader.getContentList({ contentType: 'post' });
await writer.createContent(/* … */);

Exporting a snapshot from the CLI

Generate a snapshot with the content-island export command. It exports your project’s content and writes it to disk:

npx content-island export \
  --access-token <your-read-token> \
  --snapshot-path ./content-island-snapshot.json

--snapshot-path is optional; if you omit it, the snapshot is written to ./content-island-snapshot.json, relative to the current working directory.

The command mirrors the exportSnapshot() programmatic API one-to-one (the CLI is built on it). Its flags are:

Flag	Description	Default
--access-token	Required. The access token for the export. Falls back to the env var below.	env CONTENT_ISLAND_ACCESS_TOKEN
--snapshot-path	Where the snapshot file is written.	./content-island-snapshot.json
--domain	Override the Content Island domain (for self-hosted instances).	—
--secure-protocol	Use HTTPS explicitly (this is the default).	HTTPS
--no-secure-protocol	Use HTTP instead of HTTPS (local / self-hosted instances).	—
--api-version	Override the API version used for the export.	—

The export uses HTTPS by default. Pass --no-secure-protocol only for a local or self-hosted instance served over plain HTTP:

npx content-island export \
  --access-token <your-read-token> \
  --domain localhost:3000 \
  --no-secure-protocol

Note

The exported view is token-driven: a PREVIEW_-prefixed token produces the preview view — which also pulls in draft content that isn’t published yet — while any other token produces the published view, with published content only. There is no --view flag — the view follows entirely from the token you authenticate with. See Preview mode for how preview tokens work.

On success the command prints a summary — the output path, the file size, the exportedAt timestamp and the view — and exits 0.

If the token is missing, the request fails, or the downloaded snapshot fails validation, the command writes the error to stderr (standard error) and exits with a non-zero exit code. Because it writes through a temporary file that is renamed into place only after a successful, validated download, a failed run leaves no partial or invalid file at --snapshot-path: either you get a complete snapshot or the previous file is left untouched.

A common workflow

One common setup — it depends on your team and project — is api mode in local development and snapshot mode in production builds:

• Local dev (mode: 'api') — always fresh content, no export step to remember.
• Production build (mode: 'snapshot') — fast, repeatable, with zero per-request network calls.

Drive the choice from an environment variable so the same code runs in both:

import { createClient } from '@content-island/api-client';

const client = createClient({
  accessToken: process.env.CONTENT_ISLAND_ACCESS_TOKEN,
  mode: process.env.NODE_ENV === 'production' ? 'snapshot' : 'api',
});

In production, generate the snapshot first (an export step), then run your build so it reads from the freshly exported file.

GitHub Action

This workflow exports a snapshot at build time, then builds your site in snapshot mode:

name: Build

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: 24

      - run: npm ci

      - name: Export content snapshot
        env:
          CONTENT_ISLAND_ACCESS_TOKEN: ${{ secrets.CONTENT_ISLAND_ACCESS_TOKEN }}
        run: npx content-island export

      - name: Build (snapshot mode)
        env:
          NODE_ENV: production
        run: npm run build

Note

The access token is read from a repository secret through the CONTENT_ISLAND_ACCESS_TOKEN environment variable, so it is passed to the export step without ever appearing in the build logs.