initLivePreview

Framework-agnostic initializer of Contenful Live Preview.

The method is an additional abstraction layer on top of the Live Preview SDK from Contentful. It simplifies the setup by providing a default configuration and calling the Live Preview SDK methods in the right manner.

The method has a built-in checking mechanism to determine whether the app is displayed within the Contetful Live Preview iframe. Only then it imports the Live Preview SDK dynamically, initializes it and subscribes to content changes. The object passed as the first argument must contain raw data from Contentful. It cannot be - for example - a raw data object transformed by the extractComponents method.

Signature

declare function initLivePreview(
	data: ContentfulSubscribeConfig["data"] | null,
	livePreviewConfig?: LivePreviewConfig
): Promise<VoidFunction>;

Parameters

Name	Required	Type	Description
`data`	Required	`ContentfulSubscribeConfig["data"] \| null`	A reference to the data object. If you fetched it using either `getEntry` or `getEntries` methods, you must pass the reference to the nested `items` property. See examples below.
`livePreviewConfig`	Optional	`LivePreviewConfig`	An optional configuration object that can be used to override the default configuration.

Returns

This method returns a function to unsubscribe from the Live Preview updates.

Referenced Types

ContentfulSubscribeConfig
LivePreviewConfig

Examples

Using the method can be as simple as passing it the data object and relying on the default configuration.

import { sdk } from '~/sdk.config.ts';

const { items } = await sdk.contentful.getEntries({ ... });

sdk.contentful.utils.initLivePreview(items);

The default callback will perform the Object.assign() operation on the data object passed as the first argument. If you want more control over the object update process, define your own callback. It will run whenever some changes are made in the Live Preview content form.

import { sdk } from '~/sdk.config.ts';

const { items } = await sdk.contentful.getEntries({ ... });

sdk.contentful.utils.initLivePreview(items, {
  callback: (updatedData) => {
    // Do something with the updated data...
  }
});

Usage example in a dynamic page component in Nuxt 3. Notice how we are extracting the nested items property from the data object.

import type { EntryCollection } from 'contentful';
import { sdk } from '~/sdk.config.ts';

const content: Ref<EntryCollection<any>['items'] | null> = useState(() => null)

sdk.contentful.utils.initLivePreview(content.value);

await useAsyncData(async () => {
  const { items } = await sdk.contentful.getEntries({
    content_type: 'page',
    'fields.url': url,
    include: 3,
  });
  return content.value = items;
};

Usage example in a dynamic page component in Next 13. Notice how we used the useEffect hook with empty dependencies array to make sure we subscribe for Live Preview updates only once.

As an alternative, we also encourage you to review the React-specific Live Preview implementation provided by the Contentful team.

import { useState, useEffect } from 'react';
import { sdk } from '~/sdk.config';

export default function Slug(props: any) {
 const [extractedPage, updatePage] = useState(props.content[0]);
 const extractedComponents = sdk.contentful.utils.extractComponents(extractedPage?.fields.items);

 useEffect(() => {
   sdk.contentful.utils.initLivePreview(extractedPage, { callback: updatePage });
 }, [])

 return ( ... );
}