Preview Mode

WPNuxt supports WordPress preview mode, allowing editors to preview draft and unpublished content directly in your Nuxt frontend.

How It Works

1. An editor clicks Preview in the WordPress editor
2. WordPress redirects to your Nuxt site with ?preview=true&token=<jwt_token> query parameters
3. WPNuxt's client options detect these parameters and pass them to the server
4. The server forwards authentication cookies/headers to WordPress
5. WordPress returns the draft content via GraphQL

WordPress Editor → Click "Preview"
    → https://your-nuxt-site.com/my-draft-post?preview=true&token=abc123
        → WPNuxt client detects preview params
            → Server forwards auth to WordPress GraphQL
                → Draft content returned and rendered

Client Options

WPNuxt automatically passes preview parameters from the URL to the GraphQL middleware. This is handled by the default client options:

import { defineGraphqlClientOptions } from 'nuxt-graphql-middleware/client-options'
import { useRoute } from '#imports'

export default defineGraphqlClientOptions<{
  preview?: string
  previewToken?: string
}>({
  buildClientContext() {
    const route = useRoute()

    return {
      preview: route.query.preview === 'true' ? 'true' : undefined,
      previewToken: route.query.token as string | undefined,
    }
  },
})

Server Options

The server-side options forward authentication cookies and headers to WordPress, enabling authenticated GraphQL requests for draft content:

import { defineGraphqlServerOptions } from 'nuxt-graphql-middleware/server-options'
import { getHeader } from 'h3'

export default defineGraphqlServerOptions({
  async serverFetchOptions(event, _operation, _operationName, _context) {
    return {
      headers: {
        Cookie: getHeader(event, 'cookie') || '',
        Authorization: getHeader(event, 'authorization') || '',
      },
    }
  },
})

This ensures that when a WordPress editor is logged in and previewing content, their authentication is passed through to the GraphQL API.

WordPress Configuration

Set the Preview URL

Configure WordPress to redirect previews to your Nuxt frontend. Add this to your theme's functions.php or a custom plugin:

add_filter('preview_post_link', function ($link, $post) {
    $nuxt_url = 'https://your-nuxt-site.com';
    $slug = $post->post_name ?: $post->ID;
    return $nuxt_url . '/' . $slug . '?preview=true';
}, 10, 2);

Or use the Headless WordPress plugin to configure the preview URL in the WordPress admin.

Authentication for Previews

Preview mode requires the editor to be authenticated. WPNuxt supports two approaches:

1. Cookie forwarding (default) — The server options forward WordPress auth cookies automatically. This works when your Nuxt site and WordPress share a domain or you have proper CORS configuration.
2. JWT tokens — If using the Headless Login plugin, pass a JWT token via the token query parameter. The client options extract this and pass it through as previewToken.

Displaying Preview Content

Your existing pages work with preview mode automatically. The useNodeByUri() composable will return draft content when valid preview credentials are present:

<script setup lang="ts">
const route = useRoute()

const { data: post } = await useNodeByUri(
  { uri: route.path },
  { watch: [() => route.path] }
)

// Show a preview banner when in preview mode
const isPreview = computed(() => route.query.preview === 'true')
</script>

<template>
  <div>
    <div
      v-if="isPreview"
      class="bg-yellow-100 text-yellow-800 p-3 text-center text-sm"
    >
      Preview mode — this content is not published yet.
    </div>

    <article v-if="post">
      <h1>{{ post.title }}</h1>
      <div v-sanitize-html="post.content" />
    </article>
  </div>
</template>

Disabling Cache for Previews

Preview content should not be cached. WPNuxt's server-side cache automatically bypasses caching when an Authorization header is present. For additional safety, disable client-side caching in preview mode:

const route = useRoute()
const isPreview = route.query.preview === 'true'

const { data: post } = await useNodeByUri(
  { uri: route.path },
  {
    clientCache: !isPreview,
    watch: [() => route.path],
  }
)

Testing Previews Locally

1. Start your Nuxt dev server
2. Log in to WordPress admin
3. Create or edit a post (don't publish it)
4. Click Preview — WordPress will redirect to your Nuxt site
5. If WordPress and Nuxt are on different ports, ensure cookies are forwarded correctly

Related Pages

• WordPress Setup — Configure WordPress for headless use
• Caching — How caching is bypassed for authenticated preview requests