Real-Time Content Previews in Headless WordPress: A Complete Guide

Real-time content previews are a key part of the editorial experience in WordPress. But in headless WordPress setups – where the frontend is decoupled – replicating the native preview functionality requires extra engineering.

In traditional WordPress, clicking “Preview” instantly loads the draft using the PHP theme. In a headless architecture (with Next.js, Nuxt, or Gatsby), your frontend lives elsewhere. It doesn’t automatically know about unpublished content.

This article covers:

• ✅ How real-time content previews work in headless WordPress
• 🔐 How to securely pass preview tokens between backend and frontend
• 🚀 Frontend code examples (Next.js)
• ✅ Best practices for security and performance
• ⚙️ How Sitebox simplifies the whole process

---

What Is Headless WordPress?

Headless WordPress separates the frontend and backend. WordPress handles content and admin functionality. A JavaScript framework (like React, Vue, or Svelte) powers the frontend, fetching content via REST API or GraphQL.

This gives developers full control over the frontend – but it breaks features like the native “Preview” button.

---

Why Are Previews Challenging in Headless?

In classic WordPress:

• Clicking Preview renders the draft with PHP
• Drafts live server-side and load instantly

In headless WordPress:

• The frontend doesn’t know about unpublished drafts
• It requires secure, authenticated API access
• You must implement a preview mode to simulate content before it’s published

---

How Real-Time Content Previews Work

To simulate previews in a headless environment:

1. WordPress generates a preview link with a secure token
2. Clicking the link sends the user to the frontend with the token as a query param
3. The frontend switches into preview mode
4. It fetches the draft content from WordPress via API
5. The draft is rendered — in real time, even though it’s not live

---

Generating Preview Links in WordPress

Use a filter to inject preview tokens into your URLs:

add_filter('preview_post_link', function($link, $post) {
  $secret = 'my-secret-token';
  return home_url("/api/preview?secret={$secret}&id={$post->ID}");
}, 10, 2);

🔐 Use a random, environment-specific token stored in your .env file, not hardcoded.

---

Preview Mode on the Frontend (Next.js Example)

Create a preview route:

// pages/api/preview.js
export default async function handler(req, res) {
  const { secret, id } = req.query;

  if (secret !== process.env.PREVIEW_SECRET) {
    return res.status(401).json({ message: 'Invalid token' });
  }

  res.setPreviewData({ postId: id });
  res.writeHead(307, { Location: `/posts/${id}` });
  res.end();
}

Then in your page component:

• Use getStaticProps or getServerSideProps
• Check for context.preview
• Fetch draft content if in preview mode

---

Fetching Draft Content via API

REST API Example:

curl --user "editor:app-password" \
  https://yourdomain.com/wp-json/wp/v2/posts/123?context=edit

JavaScript Fetch Example:

fetch(`https://yourdomain.com/wp-json/wp/v2/posts/${id}?context=edit`, {
  headers: {
    Authorization: `Basic ${btoa('editor:app-password')}`
  }
});

WPGraphQL Preview Example:

query PreviewPost($id: ID!) {
  post(id: $id, idType: DATABASE_ID, asPreview: true) {
    title
    content
    status
  }
}

Use asPreview: true to fetch the latest draft.

---

Best Practices for Real-Time Previews

1. 🔐 Secure Preview Routes

Use secret tokens to authenticate preview links. Never expose unauthenticated preview endpoints.

2. ⏱ Set Token Expiry

Tokens should expire within 5–15 minutes. Consider using JWTs with built-in expiration.

3. 🚫 Avoid Caching Drafts

Bypass Cloudflare, Varnish, or any CDN for preview mode to ensure up-to-date drafts render instantly.

4. 👥 Role-Based Access

Limit preview access to authors, editors, or users with edit_posts capability in WordPress.

5. 📣 Show Preview UI

Clearly show users when they’re in preview mode with a banner or badge. Provide an “Exit Preview” button to restore normal mode.

---

Conclusion

Real-time content previews are essential for editorial workflows, especially in enterprise and marketing websites. While traditional WordPress handles this automatically, headless setups require thoughtful engineering.

When implemented correctly, real-time previews:

• Improve the editor experience
• Reduce publishing errors
• Support fast, decoupled frontends

But it’s not trivial — you’ll need to handle token security, API auth, frontend routing, and preview state carefully.

---

How Sitebox Simplifies Real-Time Content Previews

Sitebox makes real-time previews effortless:

✅ Auto-Generated Tokens: Secure preview links tied to user roles and post types
✅ Live Preview Rendering: No rebuilds, just fast previews
✅ Framework Support: Out-of-the-box compatibility with Next.js, Nuxt, and others
✅ API Management: Handles both REST and GraphQL, with caching rules built-in
✅ Editor UX: Adds visual indicators and exits for preview mode

Whether you’re building a static site or full enterprise CMS, Sitebox brings real-time content previews to your headless WordPress stack with zero friction.

👉 Ready to bring real-time previews to your headless setup? Try Sitebox and empower your editors today.