@eight25-factory/live-preview

@eight25-factory/live-preview

CMS live preview, live updates, and inspector-mode field tagging for Next.js and Nuxt, with Contentful or Contentstack — plus SKILLS.md, an instruction file that teaches an AI agent to build new front-end components that preview correctly from the first commit.

Editor opens an entry → preview panel shows the site
Hovers a heading      → an Edit affordance outlines it   (inspector mode / Visual Builder)
Types                 → the page updates                 (live updates)
Production            → no tags, no SDK, nothing changed

5-minute setup

Run one command in the project root. It installs the package and the CMS SDK, then writes the wiring files:

# Contentful
npx @eight25-factory/live-preview init --write --provider contentful

# Contentstack
npx @eight25-factory/live-preview init --write --provider contentstack

# Non-interactive (accept every default, e.g. in CI or an agent)
npx @eight25-factory/live-preview init --yes --write --provider contentful

Prefer to manage dependencies yourself? Install them first and skip the automatic step:

npm install @eight25-factory/live-preview @contentful/live-preview          # Contentful
npm install @eight25-factory/live-preview @contentstack/live-preview-utils  # Contentstack
npx live-preview init --write --no-install

Works with pnpm, yarn and bun too; init picks the package manager from the lockfile.

init detects the framework, reads which CMS is configured from environment variable names (never values), asks only what it cannot infer, adds @eight25-factory/live-preview and the CMS SDK (@contentful/live-preview or @contentstack/live-preview-utils) to package.json with the project's own package manager (pass --no-install to skip), and writes:

• live-preview.config.mjs — the application-owned, non-secret configuration
• the framework wiring (provider component or plugins, preview-aware data helpers, draft-mode routes for Contentful)
• .claude/skills/live-preview/SKILL.md and a pointer in AGENTS.md, so the next AI agent that touches a component follows the rules

On a Next project it also patches next.config.ts and app/layout.tsx when they still have the create-next-app shape. Then it prints the remaining manual steps: the page, the middleware cache rule for draft-mode requests, and the preview URL to paste into the CMS. Already have a CMS client? Run init --write --no-fetch-helpers and pass state.active into it.

With the app running, npx live-preview doctor http://localhost:3000 checks the draft cookie, the tags, framing and cache headers in one go.

Using it in a component

Server Component (Next.js):

import { previewTags } from "@/lib/live-preview/server";

export default function Hero({ hero, state }) {
  const tag = previewTags(state, hero); // {} outside preview
  return (
    <section>
      <h1 {...tag("title")}>{hero.title}</h1>
      <p {...tag("body")}>{hero.body}</p>
    </section>
  );
}

Client Component with keystroke-level updates:

"use client";
import { useFieldTags } from "@/components/live-preview/context";
import { useLiveEntry } from "@/components/live-preview/useLiveEntry";

export default function Hero({ hero }) {
  const live = useLiveEntry(hero);
  const tag = useFieldTags(live);
  return <h1 {...tag("title")}>{live.title}</h1>;
}

Nuxt:

<script setup lang="ts">
const props = defineProps<{ hero: Entry }>();
const live = useLiveEntry(toRef(props, "hero"));
const tag = useFieldTags(live);
</script>
<template>
  <h1 v-bind="tag('title')">{{ live.title }}</h1>
</template>

The same tag("field") call produces data-contentful-entry-id / data-contentful-field-id / data-contentful-locale for Contentful and data-cslp="content_type.uid.locale.field" for Contentstack. Under the default policy it produces nothing outside a preview session.

What it does

• Decides preview vs production per request from Next draft mode, a session cookie (Nuxt), or Contentstack's live_preview hash, in one place.
• Tags fields for the editor with one provider-agnostic call, on the server or in the browser, with a strict policy for when tags appear.
• Builds the SDK initialization (ContentfulLivePreviewProvider props, ContentstackLivePreview.init config) from the same configuration, with no token in it.
• Routes CMS requests correctly: Preview API and preview token in preview, Delivery API otherwise; Contentstack preview hosts, hash, Timeline timestamp; never cached while previewing.
• Secures the draft-mode routes: constant-time secret check, same-origin redirect guard, SameSite=None; Secure session cookie.
• Lets the CMS frame the site by merging frame-ancestors into the Content-Security-Policy and dropping X-Frame-Options.
• Keeps navigation in preview by carrying Contentstack's session parameters across internal links.
• Ships an AI skill (SKILLS.md) with rules, recipes, a verification protocol, and a diagnosis table, installable with npx live-preview install-skills.

What it deliberately does not do

• No runtime dependency on a CMS SDK or a framework. The package is pure functions; the SDK calls live in the generated files inside your app, where you can read and change them.
• No DOM patching of its own. Contentful's SDK delivers updated data; Contentstack's SDK patches the DOM in SSR mode. This package makes both work; it does not reimplement them.
• No NEXT_PUBLIC_* tokens. The browser receives a serializable, token-free config computed on the server.

Supported integrations

Peer SDKs (install the one for your CMS): @contentful/live-preview ≥ 4, @contentstack/live-preview-utils ≥ 3.

Documentation

Requirements

Node 22 or newer. No runtime dependencies.