Content Preview

An editor drafts a campaign page in the CMS and wants to see it on the real storefront — real layout, real products, real prices — before anyone else can. Content preview does exactly that: append ?preview_token=<token> to any storefront URL and the page is server-rendered against unpublished content instead of published content.

https://shop.example.com/campaigns/summer?preview_token=pvtk_3Qm…

Everything else stays the same. Same deployment, same routes, same sections. The only thing that changes is what your connectors return, because they now see clientEnv.isPreview === true.

How the gate works

The token is a project-level secret, not a per-user credential. It travels like this:

A wrong token is not an error. The page renders published content, exactly as it would for a shopper, and nothing is thrown. The only signal is status === 'rejected' in the composable below.

Reading preview state in your app

useContentPreview() is auto-imported and safe to call from any component or composable.

<script setup lang="ts">
const { enabled, status, state } = useContentPreview();
</script>

<template>
  <div v-if="enabled" class="preview-badge">
    Preview mode
    <button @click="enabled = false">Exit</button>
  </div>
  <div v-else-if="status === 'rejected'" class="preview-badge preview-badge--error">
    Invalid preview token — showing published content.
  </div>
</template>

Return value

The four states

Driving preview from a cookie or header

The query parameter is the default source, not the only one. Register a handler on frontend-core:content-preview:resolve-token to take it over — useful when your CMS sets a preview cookie, or when you proxy previews behind a gateway that injects a header.

export default defineNuxtPlugin({
  // Must outrank frontend-core's own preview plugin.
  enforce: 'pre',
  setup(nuxtApp) {
    nuxtApp.hook('frontend-core:content-preview:resolve-token', ({ result }) => {
      result.value = useCookie('cms_preview_token').value ?? undefined;
    });
  },
});

Two constraints, both enforced by how the hook is called:

• The plugin must use enforce: 'pre'. frontend-core evaluates the token source during its own plugin setup; a handler registered later is never consulted.
• Handlers must be synchronous. You may read cookies or useRequestHeaders(), but you must not await — a returned promise is ignored.

The first handler to set result.value wins. Leave it unset to fall back to ?preview_token=.

Reacting to a preview change

Entering or leaving preview invalidates data that was fetched under the old assumption. frontend-core already handles its own two caches:

• refreshNuxtData() — every useAsyncData / useFetch in your app re-runs.
• invalidateOrchestrQueries() — every stored orchestr query result is dropped.

If you keep your own cache — a Pinia store hydrated once, a memoized CMS client — invalidate it from frontend-core:content-preview:changed:

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('frontend-core:content-preview:changed', ({ enabled }) => {
    useMyCmsStore().reset();
    console.debug(`[preview] now ${enabled ? 'on' : 'off'}`);
  });
});

The hook fires after enabled already holds the new value, on the enable transition, the disable transition, and on a token swap — a change from one token to another flips neither enabled nor Nuxt's own lifecycle callbacks, but still needs the same invalidation.

Serving unpublished content from a handler

Preview is only useful if your connectors act on it. Read clientEnv.isPreview in any query handler, link handler, component resolver, or action handler:

export default defineMyCmsQuery(PageByPathQuery, async ({ context, input, clientEnv }) => {
  const { id } = await context.cmsClient.page({
    path: input.path,
    // Most headless CMSs expose drafts through a separate stage or endpoint.
    stage: clientEnv.isPreview ? 'DRAFT' : 'PUBLISHED',
  });

  return { id };
});

isPreview is a server-verified fact by the time your handler sees it — see Client Environment for the full trust boundary.

Caching

Preview content is volatile and per-editor. It is kept out of every cache, deliberately:

The private, no-store header is set for any presented token, granted or rejected. A rejected render still embeds the token in the hydration payload, and a CDN that ignores query strings in its cache key could otherwise hand that response to a shopper.

The verify endpoint

POST /api/frontend/preview-verify answers { granted: boolean } for a presented token. The client uses it to resolve pending into active or rejected.

// POST /api/frontend/preview-verify
{ "token": "pvtk_3Qm…" }

// → 200
{ "granted": true }

It is unauthenticated on purpose: the browser calling it carries no project secret, and appending ?preview_token=X to any page is the same oracle. It is a UI hint only — authorization for real data is the gate that runs inside resolveClientEnv() on every orchestr request regardless, so a client that asserts isPreview: true without ever calling this endpoint still receives published content. Both paths share one implementation and cannot drift apart.

Brute-force resistance comes from token entropy. The response never contains the expected token, its length, or a reason.

Security notes

• The token is a project-wide secret. Anyone holding it sees all unpublished content for that project. Share it with editors the way you would share a staging password, and rotate it when someone leaves.
• It is never sent to the browser as configuration. It lives in private runtime config. It reaches the browser only when someone typed it into a URL.
• A wrong token is indistinguishable from no token as far as rendered output goes. This is intentional: a preview URL that leaks to a shopper renders the ordinary published page.
• Preview never reaches a shared cache. See Caching above.

Related

• Hooks — the two content-preview hooks in full.
• Client Environment — how isPreview is resolved and what else clientEnv carries.
• Caching — orchestr's three cache layers.
• Environments & Staging — previewing code changes, as opposed to content.