@contentful/live-preview

@contentful/live-preview

Live preview SDK for both the inspector mode connection + live content updates by Contentful.

Getting started

Requirements

• Node.js: >=16.15.1

To install live preview simply run one of the following commands.

yarn add @contentful/live-preview

or

npm install @contentful/live-preview

Documentation

• Developer Documentation

Initializing the SDK

To establish a communication between your preview frontend and Contentful, you simply need to initialize the live preview SDK. This can be done by executing the following command:

import { ContentfulLivePreview } from '@contentful/live-preview';

...

ContentfulLivePreview.init();

Init Configuration

The init command also accepts a configuration object that allows you to customize your live preview SDK experience. The following options are available:

import { ContentfulLivePreview } from '@contentful/live-preview';

...

ContentfulLivePreview.init({
  enableInspectorMode: false, // This allows you to toggle the inspector mode which is on by default
  enableLiveUpdates: false, // This allows you to toggle the live updates which is on by default
  debugMode: false, // This allows you to toggle the debug mode which is off by default
});

Inspector Mode (field tagging)

To use the inspector mode, you need to tag fields by adding the live preview data-attributes (data-contentful-entry-id, data-contentful-field-id, data-contentful-locale) to the rendered HTML element output.

You can do this in React via our helper function.

The necessary styles for the live edit tags can be found in the @contentful/live-preview/style.css file.

import { ContentfulLivePreview } from '@contentful/live-preview';
import '@contentful/live-preview/style.css';
...

<h1 {...ContentfulLivePreview.getProps({ entryId: id, fieldId: 'title', locale })}>
  {title}
</h1>

Live Updates

Live Updates from the editor to your applications are out of the box only supported for React.js at the moment. The updates are only happening on the client-side and in the live preview environment of contentful.

import { useContentfulLiveUpdates } from '@contentful/live-preview/react';

// ...
const updated = useContentfulLiveUpdates(originalData, locale);
// ...

Integration with Next.js

To use the Contentful LivePreivew SDK with Next.js, you can either use one of the contentful starter templates, or do the following steps to add it to an existing project.

1. Add the @contentful/live-preview package to your project

yarn add @contentful/live-preview

or

npm install @contentful/live-preview

1. Initialize the SDK with the ContentfulLivePreviewProvider and add the stylesheet for field tagging inside _app.tsx or _app.js. The ContentfulLivePreviewProvider accepts the same arguments as the init function.

import '@contentful/live-preview/style.css';
import { ContentfulLivePreview } from '@contentful/live-preview/react';

const CustomApp = ({ Component, pageProps }) => (
  <ContentfulLivePreviewProvider>
    <Component {...pageProps}>
  </ContentfulLivePreviewProvider>
)

This provides the posibility to only enable live updates and the inspector mode inside the preview mode:

import '@contentful/live-preview/style.css';
import { ContentfulLivePreview } from '@contentful/live-preview/react';

const CustomApp = ({ Component, pageProps }) => (
  <ContentfulLivePreviewProvider enableInspectorMode={pageProps.previewActive} enableLiveUpdates={pageProps.previewActive}>
    <Component {...pageProps}>
  </ContentfulLivePreviewProvider>
)

1. Add field tagging and live updates to your component

export default function BlogPost: ({ blogPost }) {
  const inspectorProps = useContentfulInspectorMode()
  // Live updates for this component
  const data = useContentfulLiveUpdates(
    blogPost,
    locale
  );

  return (
    <Section>
      <Heading as="h1">{data.heading}</Heading>
      {/* Text is tagged and can be clicked to open the editor */}
      <Text
        as="p"
        {...inspectorProps({
          entryId: data.sys.id,
          fieldId: 'text',
          locale,
        })}>
        {data.text}
      </Text>
    </Section>
  );
}

It doesn't matter if the data is loaded with getServerSideProps, getStaticProps or if you load it in any other way.
It's necessary that the provided information to useContentfulLiveUpdate contains the sys.id for identifation and only non-transformed fields can be updated.
(For GraphQL also the __typename needs to be provided)

Tip: If you want to tag multiple fields of an entry, you can also provide initial arguments to the hook:

export default function BlogPost: ({ blogPost }) {
  const inspectorProps = useContentfulInspectorMode({ entryId: data.sys.id, locale })

  return (
    <Section>
      <Heading as="h1" {...inspectorProps({ fieldId: 'heading' })}>{data.heading}</Heading>
      <Text as="p" {...inspectorProps({ fieldId: 'text' })}>
        {data.text}
      </Text>
    </Section>
  )

1. Enable preview mode

We suggest using the preview mode and the Content Preview API for the best experience.

For a full guide checkout this free course

1. In Contentful, define the preview environment and configure the preview URL for your Next.js application. Once you open an entry with a configured preview URL, you can use the live preview and all its features.

That's it! You should now be able to use the Contentful live preview SDK with Next.js.

Integrating with Gatsby

To use the Contentful live preview SDK with Gatsby, you can start with the gatsby starter contentful homepage

1. Add the @contentful/live-preview package to your Gatsby project by running one of the following commands:

yarn add @contentful/live-preview

or

npm install @contentful/live-preview

1. In your gatsby-browser.js file, import the live preview styles and initialize the SDK:

import '@contentful/live-preview/style.css';

import React from "react";
import { ContentfulLivePreview } from '@contentful/live-preview/react';

export const wrapRootElement = ({ element }) => (
  <ContentfulLivePreviewProvider>{element}</ContentfulLivePreviewProvider>
)

1. In order to tag fields and use live updates, you need to add the contentful_id property to the GraphQL schema. For example, to extend the HomepageHero interface:

interface HomepageHero implements Node & HomepageBlock {
  id: ID!
  contentful_id: String! # add this property
  heading: String!
  text: String
}

type ContentfulHomepageHero implements Node & HomepageHero & HomepageBlock @dontInfer {
  id: ID!
  contentful_id: String! # and also here
  heading: String!
  text: String
}

1. Update the corresponding component to load the contentful_id property:

export const query = graphql`
  fragment HomepageHeroContent on HomepageHero {
    __typename
    id
    contentful_id # add this property
    heading
    text
  }
`;

1. Add tagging and live updates to your component:

export default function Hero({ contentful_id, ...props }) {
  const inspectorProps = useContentfulInspectorMode()
  // Live updates for this component
  const data = useContentfulLiveUpdates(
    {
      ...props,
      sys: { id: props.contentful_id },
    },
    locale
  );

  return (
    <Section>
      <Heading as="h1">{data.heading}</Heading>
      {/* Text is tagged and can be clicked to open the editor */}
      <Text
        as="p"
        {...inspectorProps({
          entryId: contentful_id,
          fieldId: 'text',
          locale,
        })}>
        {data.text}
      </Text>
    </Section>
  );
}

1. In Contentful, define the preview environment and configure the preview URL for your Gatsby site. Once you open an entry with a configured preview URL, you can use the live preview and all its features.

That's it! You should now be able to use the Contentful live preview SDK with Gatsby.

Code of Conduct

We want to provide a safe, inclusive, welcoming, and harassment-free space and experience for all participants, regardless of gender identity and expression, sexual orientation, disability, physical appearance, socioeconomic status, body size, ethnicity, nationality, level of experience, age, religion (or lack thereof), or other identity markers.

Read our full Code of Conduct.

License

The live preview package is open source software licensed as MIT.