Set up Experiences SDK with Gatsby

Overview

This guide explains how to integrate a Gatsby project with Experiences from scratch. Throughout the guide you can use this completed Gatsby example set as a reference.

Set up Gatsby project and install Contentful dependencies

1. npm init gatsby
2. Pick a name and directory for your project. Select the following options:
   • Typescript: Yes
   • CMS: None
   • Styling system: None
   • Additional features: Done
3. cd {project name}
4. npm i @contentful/experiences-sdk-react contentful

Create the Contentful client

Create a Contentful client

A Contentful client enables you to fetch any experience entry based on your Contentful space and environment.

1. Create a file named useContentfulClient.ts in the /src/utils directory, so the file path is /src/utils/useContentfulClient.ts.
2. Paste the following code block:

import { useMemo } from 'react';
import { createClient } from 'contentful';

type Props = {
  isPreview?: boolean;
}

export const useContentfulClient = ({isPreview}: Props) => {
  const client = useMemo(() => {
    const clientConfig = {
      space: process.env.GATSBY_CTFL_SPACE || '',
      environment: process.env.GATSBY_CTFL_ENVIRONMENT || '',
      host: 'cdn.contentful.com', // Alternatively can be 'preview.contentful.com' depending on your API preferences
      accessToken: isPreview
        ? process.env.GATSBY_CTFL_PREVIEW_ACCESS_TOKEN || ''
        : process.env.GATSBY_CTFL_ACCESS_TOKEN || '',
      experienceTypeId: process.env.GATSBY_CTFL_EXPERIENCE_TYPE || '',
    };
    return createClient(clientConfig);
  }, []);

  return { client };
};

Create the page component that a slug attaches to

1. In the pages directory, create a directory named [locale] and then a file called [slug].tsx under the [locale] directory.
2. Paste the following code block into [slug].tsx:

import { useFetchBySlug, ExperienceRoot } from '@contentful/experiences-sdk-react';
import { PageProps } from 'gatsby';
import React from 'react';
import { useContentfulClient } from '../../utils/useContentfulClient';

type PathParams = {
  locale: string;
  slug: string,
  isPreviewString: string;
};

const experienceTypeId = process.env.GATSBY_CTFL_EXPERIENCE_TYPE || '';

export default function StudioExperiencePage(pageProps: PageProps) {
  const { locale = 'en-US', slug = 'home-page', } = pageProps.params as PathParams;
  const isPreview = new URL(pageProps.location.href).searchParams.get('isPreview') === 'true';
  const { client } = useContentfulClient({ isPreview });

  const { experience, error, isLoading } = useFetchBySlug({
    slug,
    localeCode: locale,
    client,
    experienceTypeId,
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>{error.message}</div>;

  return <ExperienceRoot experience={experience} locale={locale} />;
}

Set up the Environment Variables

Create a file named env.development in the root directory of your project, at the same level as the gatsby-config.ts file. Paste the following code block into the file and set the appropriate values.

GATSBY_CTFL_ENVIRONMENT=
GATSBY_CTFL_SPACE=
GATSBY_CTFL_ACCESS_TOKEN=
GATSBY_CTFL_PREVIEW_ACCESS_TOKEN=
GATSBY_CTFL_EXPERIENCE_TYPE=
GATSBY_CTFL_DOMAIN=

The environment variables from the code block above are used by useContentfulClient.ts to fetch your experience entries.

Hook up the SDK to Experiences UI

Once you have completed all the steps above, follow these instructions to connect your Gatsby project to the Experiences UI and view it running locally:

1. In the Contentful web app, create a new experience following the steps in Create an experience.
2. Set up content preview.
   In the Contentful web app, set up a new content preview platform. Under the Preview URL area, select the Experiences toggle and set the Preview URL for Experiences to:

   http://localhost:8000/{entry.fields.slug}?isPreview=true

   This assumes that the Gatsby app runs on port 8000 by default. Make sure to set your preview setting to the created preview setting.
3. Run your Gatsby project locally by running npm run develop.
4. Refresh the Experiences UI and view your Gatsby app connected to Experiences.
5. (Optional) Make changes and publish your Experience. In the experience editor, click Open preview to see your experience live locally.