Live preview - Live updates

Overview

Live updates is an advanced live preview feature that allows you to preview your changes without clicking the “Refresh preview” button. Whenever content is updated, the changes are immediately displayed in the live preview pane.

Setup

Implementation with Vanilla JS and React

1. Initialize the live preview SDK with the live preview provider.

1
import { ContentfulLivePreview } from '@contentful/live-preview';
2
3
ContentfulLivePreview.init({
4
  locale: 'en-US', // This is required and allows you to set the locale once and have it reused throughout the preview
5
  enableInspectorMode: false, // This allows you to toggle the inspector mode which is on by default
6
  enableLiveUpdates: false, // This allows you to toggle the live updates which is on by default
7
  debugMode: false, // This allows you to toggle the debug mode which is off by default
8
  targetOrigin: 'https://app.contentful.com', // This allows you to configure the allowed host of the live preview (default: ['https://app.contentful.com', 'https://app.eu.contentful.com'])
9
});

2. Import the useContentfulLiveUpdates hook and pass the original and full (untransformed) API response data to it. If you’re using inspector mode with Content Source Maps, make sure to pass the encoded result to useContentfulLiveUpdates. The hook then returns the live updated data in real time. See an example in the code snippet below:

1
import { ContentfulLivePreview } from '@contentful/live-preview';
2
3
/**
4
 * Subscribe to data changes from the Editor, returns a function to unsubscribe
5
 * Will be called once initially for the restored data
6
 */
7
const unsubscribe = ContentfulLivePreview.subscribe({
8
  data, //the JSON response from the CPA for an entry/asset or an array of entries (or assets)
9
  locale,
10
  callback, //is a function to be called when the entry/asset is updated in Contentful to tell the frontend to update the preview. This callback is what makes the frontend update instantaneously when typing in a field in the editor.
11
});

Implementation with Next.js app router

1. Create a Next.js client component where you initialize the ContentfulLivePreviewProvider from the SDK.

1
"use client";
2
3
import { ContentfulLivePreviewInitConfig } from "@contentful/live-preview";
4
import { ContentfulLivePreviewProvider } from "@contentful/live-preview/react";
5
import { PropsWithChildren } from "react";
6
7
export function ContentfulPreviewProvider({
8
  children,
9
  ...props
10
}: PropsWithChildren<ContentfulLivePreviewInitConfig>) {
11
  return (
12
    <ContentfulLivePreviewProvider {...props}>
13
      {children}
14
    </ContentfulLivePreviewProvider>
15
  );
16
}

Once the provider is set up in the client component, you can wrap your server component app with it:

1
import { ContentfulPreviewProvider } from "../components/contentful-preview-provider";
2
3
export default function Home() {
4
  const { isEnabled } = draftMode();
5
  return (
6
    <ContentfulLivePreviewProvider
7
      locale="en-US" // This is required and allows you to set the locale once and have it reused throughout the preview
8
      enableInspectorMode // This allows you to toggle the inspector mode which is on by default
9
      enableLiveUpdates // This allows you to toggle the live updates which is on by default
10
      debugMode // This allows you to toggle the debug mode which is off by default
11
      targetOrigin="https://app.contentful.com" // This allows you to configure the allowed host of the live preview (default: ['https://app.contentful.com', 'https://app.eu.contentful.com'])
12
    >
13
      <main>...</main>
14
    </ContentfulLivePreviewProvider>
15
  );
16
}

For a full example visit the examples directory on Github.

2. The useContentfulLiveUpdates hook needs to be called in a client component:

1
"use client";
2
3
import { useContentfulLiveUpdates } from "@contentful/live-preview/react";
4
5
// entry has been fetched in a Server Component higher up the tree and passed down via props
6
export const Renderer = ({ entry }) => {
7
  const updatedEntry = useContentfulLiveUpdates(entry);
8
  return (
9
    <>
10
      <h1>{updatedEntry.fields.title}</h1>
11
    </>
12
  );
13
};

I don’t want to use any client components

For customers who prefer not to use client components in Next.js, we recommend implementing a lightweight JavaScript script. This script is designed to trigger a revalidation process via a specified endpoint whenever changes are saved in Contentful, and then it automatically reloads the iframe. Simply place the script in the public folder:

1
import { ContentfulLivePreview } from '@contentful/live-preview';
2
3
ContentfulLivePreview.init({
4
  locale: 'en-US',
5
  debugMode: true,
6
  enableLiveUpdates: true,
7
});
8
9
ContentfulLivePreview.subscribe('save', {
10
  callback: async () => {
11
    const pathname = window.location.pathname;
12
    await fetch(`/api/revalidate?pathname=${pathname}`);
13
    window.location.reload();
14
  },
15
});

The revalidation endpoint located in app/revalidate/route.ts triggers the revalidation of a specific path based on a query string parameter (pathname) from the request URL:

1
import { revalidatePath } from 'next/cache';
2
3
function getQSParamFromURL(key: string, url: string): string | null {
4
  if (!url) return '';
5
  const search = new URL(url).search;
6
  const urlParams = new URLSearchParams(search);
7
  return urlParams.get(key);
8
}
9
10
export async function GET(request: Request) {
11
  const path = getQSParamFromURL('pathname', request.url);
12
13
  if (path) {
14
    revalidatePath(path);
15
  }
16
  return new Response('OK');
17
}

This ensures that the page doesn’t reload unnecessarily when updates are made to fields not currently displayed. For a full example visit the examples directory on Github.

Provider configuration

The ContentfulLivePreviewProvider accepts parameters that allow you to customize your live preview SDK experience. The following options are available:

1
import { ContentfulLivePreviewProvider } from '@contentful/live-preview/react';
2
3
<ContentfulLivePreviewProvider
4
  locale="set-your-locale-here" // Required: allows you to set the locale once and have it reused throughout the preview.
5
  enableInspectorMode={false} // Optional: allows you to toggle inspector mode which is on by default.
6
  enableLiveUpdates={false} // Optional: allows you to toggle live updates which are on by default.
7
  targetOrigin="https://app.contentful.com" // Optional: allows you to configure the allowed host(s) of live preview (default: ['https://app.contentful.com', 'https://app.eu.contentful.com'])
8
  debugMode={false} // Optional: allows you to toggle debug mode which is off by default.
9
>

To optimize non-preview websites, it is advisable to disable live preview functionality by setting both enableInspectorMode and enableLiveUpdates to “false”. By doing so, any specific data related to live preview, such as data-attributes, is removed.

Known issues and limitations

• GraphQL filters (e.g. filters in the Array field type) or filtering using the select query parameter on the Content Preview API (CPA).
• We currently do not support multiple locales within a single GraphQL query or a single CPA response. Therefore, the withAllLocales chain modifier of the JS Client SDK is not supported.
• Live updates work only with untransformed data. Ensure that the response from the CPA or GraphQL is provided to the hook in its full and original form, with any potential transformations applied afterwards. Exception: If you’re using inspector mode with Content Source Maps, pass the encoded result into useContentfulLiveUpdates.
• Contentful Functions that resolve data in the delivery context are not compatible with live updates.