Combining external data with Experiences

1
// src/services/pim.ts
2
import { useQuery } from '@tanstack/react-query';
3
4
export const convertIdToPimId = (productId: string) =>
5
  `gid://shopify/Product/${productId}`;
6
7
export const convertPimIdToId = (pimId: string) =>
8
  pimId.replace('gid://shopify/Product/', '');
9
10
type ProductPrice = {
11
  amount: string;
12
  currencyCode: string;
13
};
14
15
type ProductPriceRange = {
16
  minVariantPrice: ProductPrice;
17
  maxVariantPrice: ProductPrice;
18
};
19
20
type ProductImage = {
21
  id: string;
22
  url: string;
23
};
24
25
export type ProductData = {
26
  id: string;
27
  title: string;
28
  description: string;
29
  priceRange: ProductPriceRange;
30
  featuredImage: ProductImage;
31
};
32
33
type ProductApiResponse = {
34
  product: ProductData;
35
};
36
37
type FetchResponse<T> = {
38
  data: T;
39
};
40
41
/** Fetches the product data for a single product ID using GraphQL. */
42
export const fetchProductData = async (
43
  productId: string
44
): Promise<ProductData> => {
45
  const response = await fetch('https://mock.shop/api', {
46
    body: JSON.stringify({
47
      query: /* GraphQL */ `
48
        {
49
          product(id: "gid://shopify/Product/${productId}") {
50
            id
51
            title
52
            description
53
            priceRange {
54
              minVariantPrice {
55
                amount
56
                currencyCode
57
              }
58
              maxVariantPrice {
59
                amount
60
                currencyCode
61
              }
62
            }
63
            featuredImage {
64
              id
65
              url
66
            }
67
          }
68
        }
69
      `,
70
    }),
71
    method: 'POST',
72
    headers: {
73
      accept: 'application/json',
74
      'content-type': 'application/json',
75
    },
76
    // Facilitate Next's built-in caching
77
    cache: 'force-cache',
78
  });
79
80
  const result = (await response.json()) as FetchResponse<ProductApiResponse>;
81
  return result.data.product;
82
};
83
84
/** Fetches all product data for a list of product IDs in a batch using GraphQL. */
85
export const fetchProductsData = async (
86
  productIds: string[]
87
): Promise<ProductData[]> => {
88
  const response = await fetch('https://mock.shop/api', {
89
    body: JSON.stringify({
90
      query: /* GraphQL */ `
91
        query searchProducts($ids: [ID!]!) {
92
          nodes(ids: $ids) {
93
            ... on Product {
94
              id
95
              title
96
              description
97
              priceRange {
98
                minVariantPrice {
99
                  amount
100
                  currencyCode
101
                }
102
                maxVariantPrice {
103
                  amount
104
                  currencyCode
105
                }
106
              }
107
              featuredImage {
108
                id
109
                url
110
              }
111
            }
112
          }
113
        }
114
      `,
115
      variables: {
116
        ids: Array.from(new Set(productIds)).map(convertIdToPimId),
117
      },
118
    }),
119
    method: 'POST',
120
    headers: {
121
      accept: 'application/json',
122
      'content-type': 'application/json',
123
    },
124
    // Facilitate Next's built-in caching
125
    cache: 'force-cache',
126
  });
127
128
  const result = (await response.json()) as FetchResponse<{
129
    nodes: ProductData[];
130
  }>;
131
132
  return result.data.nodes;
133
};
134
135
/** Fetches the product data for a single product ID via the dedicated API endpoint for client-side use. */
136
export const fetchProductDataFromApi = async (
137
  productId: string
138
): Promise<ProductData> => {
139
  const response = await fetch(`/api/pim/${productId}`);
140
  if (!response.ok) {
141
    throw new Error('Failed to fetch product data');
142
  }
143
  return response.json();
144
};
145
146
/** React Query hook for client-side product data fetching. */
147
export const useClientSideProductData = (
148
  productId: string,
149
  enabled?: boolean
150
) => {
151
  return useQuery({
152
    queryKey: ['product', productId],
153
    queryFn: () => fetchProductDataFromApi(productId),
154
    staleTime: 5 * 60 * 1000,
155
    gcTime: 10 * 60 * 1000,
156
    enabled: !!productId && enabled,
157
  });
158
};

1
// src/utils/products.ts
2
import { Experience } from '@contentful/experiences-sdk-react';
3
import { EntityStore } from '@contentful/experiences-core';
4
import { ComponentTreeNode } from '@contentful/experiences-core/types';
5
import {
6
  convertPimIdToId,
7
  fetchProductsData,
8
  ProductData,
9
} from '../../../services/pim';
10
11
const getProductNodes = (nodes: ComponentTreeNode[]): ComponentTreeNode[] =>
12
  nodes.reduce((acc, node) => {
13
    // Only pay attention to nodes with the right definition IDs of the relevant custom components
14
    if (['custom-price', 'custom-product'].includes(node.definitionId)) {
15
      acc.push(node);
16
    }
17
    // Recurse into children
18
    if (node.children) {
19
      acc.push(...getProductNodes(node.children));
20
    }
21
    return acc;
22
  }, [] as ComponentTreeNode[]);
23
24
const isValidProductId = (productId: unknown): productId is string => {
25
  return typeof productId === 'string' && productId.length > 0;
26
};
27
28
export const extractProductIds = (
29
  experience: Experience<EntityStore>
30
): string[] => {
31
  // Get all nodes with the right definition IDs of the relevant custom components
32
  // Parsing the tree is a NOT OFFICIALLY SUPPORTED strategy.
33
  // We're exploring having a standalone SDK method for this in a future version, so use at your own risk.
34
  const nodes = getProductNodes(
35
    experience?.entityStore?.experienceEntryFields?.componentTree.children ?? []
36
  )
37
    .map((node) => {
38
      // Duck-type check for the right type of the custom variable
39
      if (node.variables.product.type === 'UnboundValue') {
40
        // Get the effective product ID from the unbound value store
41
        const productId =
42
          experience?.entityStore?.unboundValues[node.variables.product.key];
43
        return productId?.value;
44
      }
45
46
      return undefined;
47
    })
48
    // Filter out invalid product IDs (e.g., `undefined` from above due to failed duck-type check or empty strings)
49
    .filter(isValidProductId);
50
51
  // Return unique product IDs to prevent overfetching
52
  return Array.from(new Set(nodes));
53
};
54
55
export const fetchProducts = async (
56
  productIds: string[]
57
): Promise<Record<string, ProductData>> => {
58
  // Fetch all products from the PIM system in a batch
59
  const products = await fetchProductsData(productIds);
60
61
  // Return a map of product IDs to product data for easy access using product IDs as keys
62
  return Object.fromEntries(
63
    await Promise.all(
64
      products.map((product) => [convertPimIdToId(product.id), product])
65
    )
66
  );
67
};

1
// src/app/api/pim/[id]/route.ts
2
import type { NextRequest } from 'next/server';
3
import { fetchProductData } from '../../../services/pim';
4
5
export async function GET(
6
  _req: NextRequest,
7
  ctx: RouteContext<'/api/pim/[id]'>
8
) {
9
  const { id } = await ctx.params;
10
  const product = await fetchProductData(id);
11
  return Response.json(product);
12
}

1
export type CustomComponentProps<T> = T & {
2
  className?: string;
3
  isEditorMode?: boolean;
4
};

1
// src/components/PriceComponent.tsx
2
import { FC } from 'react';
3
import { useFormatPrice } from '../../../utils/format';
4
import { usePrefetchedProducts } from './ProductProvider';
5
import { useClientSideProductData } from '../../../services/pim';
6
7
type PriceComponentProps = {
8
  productId: string;
9
  isEditorMode?: boolean;
10
};
11
12
export const PriceComponent: FC<PriceComponentProps> = ({
13
  productId,
14
  isEditorMode,
15
}) => {
16
  const formatPrice = useFormatPrice();
17
  // Get all prefetched products from the server side
18
  const products = usePrefetchedProducts();
19
  // Get the product data for the current product ID from the prefetched products
20
  const product = products[productId];
21
  // When in editor mode or we don't have the product data pre-fetched on the server side, we need to fetch it on the client side
22
  const { data, isLoading } = useClientSideProductData(
23
    productId,
24
    // Enable for editor/canvas mode or if the product data was not prefetched on the server side properly
25
    isEditorMode || !product
26
  );
27
  // Use the prefetched product data if available, otherwise use the client-side fetched data
28
  const productData = product ?? data;
29
30
  // Catch fresh instances of the component without a product ID being set yet (i.e. editor may be working on it still)
31
  if (!productId) {
32
    return 'TBD';
33
  }
34
35
  // Loading state in case the product data is being fetched on the client side
36
  if (isLoading) {
37
    return 'Fetching…';
38
  }
39
40
  // Last resort placeholder in case no product could be resolved both on the server side and client side for the given ID
41
  if (!productData) {
42
    return 'n/a';
43
  }
44
45
  // Get price from product data
46
  const { priceRange } = productData;
47
  const minPrice = parseFloat(priceRange.minVariantPrice.amount);
48
  const maxPrice = parseFloat(priceRange.maxVariantPrice.amount);
49
  const currency = priceRange.minVariantPrice.currencyCode;
50
51
  return (
52
    <>
53
      {minPrice === maxPrice ? (
54
        formatPrice(minPrice, currency)
55
      ) : (
56
        <>
57
          {formatPrice(minPrice, currency)}-{formatPrice(maxPrice, currency)}
58
        </>
59
      )}
60
    </>
61
  );
62
};

1
// src/components/PriceComponentRegistration.tsx
2
import { ComponentRegistration } from '@contentful/experiences-sdk-react';
3
import { Suspense } from 'react';
4
import clsx from 'clsx';
5
import { PriceComponent } from './PriceComponent';
6
import styles from './PriceComponent.module.css';
7
8
type PriceComponentProps = CustomComponentProps<{
9
  product: string;
10
}>;
11
12
export const PriceComponentRegistration: ComponentRegistration = {
13
  component: ({
14
    className,
15
    product,
16
    isEditorMode,
17
    // https://www.contentful.com/developers/docs/experiences/custom-components/#component-requirements
18
    ...rest
19
  }: PriceComponentProps) => {
20
    return (
21
      <div className={clsx(styles.price, className)} {...rest}>
22
        <Suspense fallback={<div>Loading…</div>}>
23
          <PriceComponent productId={product} isEditorMode={isEditorMode} />
24
          {isEditorMode && <div className={styles.info}>{product}</div>}
25
        </Suspense>
26
      </div>
27
    );
28
  },
29
  options: {
30
    enableEditorProperties: {
31
      isEditorMode: true,
32
    },
33
    wrapComponent: false,
34
  },
35
  definition: {
36
    id: 'custom-price',
37
    name: 'Price',
38
    category: 'External Content',
39
    variables: {
40
      product: {
41
        displayName: 'Product ID',
42
        type: 'Text',
43
        group: 'content',
44
      },
45
    },
46
  },
47
};

1
// src/components/ProductComponent.tsx
2
import { FC } from 'react';
3
import { Card, Image, Tag, Flex } from 'antd';
4
import { usePrefetchedProducts } from './ProductProvider';
5
import { useClientSideProductData } from '../../../services/pim';
6
import { PriceComponent } from './PriceComponent';
7
8
type ProductComponentProps = {
9
  productId: string;
10
  isEditorMode?: boolean;
11
};
12
13
export const ProductComponent: FC<ProductComponentProps> = ({
14
  productId,
15
  isEditorMode,
16
}) => {
17
  const products = usePrefetchedProducts();
18
  const product = products[productId];
19
20
  // When in editor mode or we don't have the product data pre-fetched on the server side, we need to fetch it on the client side
21
  const { data, isLoading } = useClientSideProductData(
22
    productId,
23
    isEditorMode || !product
24
  );
25
  const productData = product ?? data;
26
27
  if (!productId) {
28
    return <Card>TBD</Card>;
29
  }
30
31
  if (isLoading) {
32
    return 'Fetching…';
33
  }
34
35
  if (!productData) {
36
    return 'n/a';
37
  }
38
39
  return (
40
    <Card
41
      cover={
42
        <Image src={productData.featuredImage.url} alt={productData.title} />
43
      }
44
      extra={isEditorMode ? <Tag>{productId}</Tag> : null}
45
    >
46
      <Flex gap="middle" vertical>
47
        <Card.Meta
48
          title={productData.title}
49
          description={productData.description}
50
        />
51
        <PriceComponent productId={productId} isEditorMode={isEditorMode} />
52
      </Flex>
53
    </Card>
54
  );
55
};

1
// src/components/ProductComponentRegistration.tsx
2
import { ComponentRegistration } from '@contentful/experiences-sdk-react';
3
import clsx from 'clsx';
4
import { ProductComponent } from './ProductComponent';
5
6
type ProductComponentProps = CustomComponentProps<{
7
  product: string;
8
}>;
9
10
export const ProductComponentRegistration: ComponentRegistration = {
11
  component: ({
12
    className,
13
    product,
14
    isEditorMode,
15
    // https://www.contentful.com/developers/docs/experiences/custom-components/#component-requirements
16
    ...rest
17
  }: ProductComponentProps) => {
18
    return (
19
      <div className={clsx(className)} {...rest}>
20
        <ProductComponent productId={product} isEditorMode={isEditorMode} />
21
      </div>
22
    );
23
  },
24
  options: {
25
    enableEditorProperties: {
26
      isEditorMode: true,
27
    },
28
    wrapComponent: false,
29
  },
30
  definition: {
31
    id: 'custom-product',
32
    name: 'Product',
33
    category: 'External Content',
34
    variables: {
35
      product: {
36
        displayName: 'Product ID',
37
        type: 'Text',
38
        group: 'content',
39
      },
40
    },
41
  },
42
};

1
// src/components/ProductProvider.tsx
2
'use client';
3
4
import { createContext, FC, PropsWithChildren, useContext } from 'react';
5
import { ProductData } from '../../../services/pim';
6
7
const PrefetchedProductContext = createContext<Record<string, ProductData>>({});
8
9
/** Returns a map of all prefetched products based on server-side extracted PIM data. */
10
export const usePrefetchedProducts = () => useContext(PrefetchedProductContext);
11
12
type PrefetchedProductProviderProps = PropsWithChildren<{
13
  products: Record<string, ProductData>;
14
}>;
15
16
/** Provides a map of all prefetched products from the server side to the client component tree. */
17
export const PrefetchedProductProvider: FC<PrefetchedProductProviderProps> = ({
18
  children,
19
  products,
20
}: PrefetchedProductProviderProps) => {
21
  return (
22
    <PrefetchedProductContext.Provider value={products}>
23
      {children}
24
    </PrefetchedProductContext.Provider>
25
  );
26
};

1
// src/app/[locale]/[slug]/page.tsx
2
import { Layout, LayoutHeader, LayoutContent, LayoutFooter } from 'antd';
3
import { getExperience } from '../../../getExperience';
4
import { extractProductIds, fetchProducts } from '../../../utils/products';
5
import { detachExperienceStyles } from '@contentful/experiences-sdk-react';
6
import { Experience } from '../../../components/Experience';
7
import { Header } from '../../../components/Header';
8
import { Footer } from '../../../components/Footer';
9
import styles from './page.module.css';
10
11
type Page = {
12
  params: Promise<{ locale?: string; slug?: string; preview?: string }>;
13
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
14
};
15
16
export default async function ExperiencePage({ params, searchParams }: Page) {
17
  const { locale = 'en-US', slug = 'home-page' } = (await params) || {};
18
  const { isPreview, expEditorMode } = (await searchParams) || {};
19
  const preview = isPreview === 'true';
20
  const editorMode = expEditorMode === 'true';
21
  const { experience, error } = await getExperience(
22
    slug,
23
    locale,
24
    preview,
25
    editorMode
26
  );
27
28
  if (error) {
29
    return <>{error.message}</>;
30
  }
31
32
  // Extract product IDs from experience and fetch the products on the server side
33
  const productIds = experience ? extractProductIds(experience) : [];
34
  const products = await fetchProducts(productIds);
35
36
  // Extract the styles from the experience
37
  const stylesheet = experience ? detachExperienceStyles(experience) : null;
38
39
  // Experience currently needs to be stringified manually to be passed to the component
40
  const experienceJSON = experience ? JSON.stringify(experience) : null;
41
42
  return (
43
    <Layout className={styles.layout}>
44
      {stylesheet && <style>{`{stylesheet}`}</style>}
45
      <LayoutHeader className={styles.header}>
46
        <Header />
47
      </LayoutHeader>
48
      <LayoutContent className={styles.content}>
49
        <Experience
50
          experienceJSON={experienceJSON}
51
          locale={locale}
52
          products={products}
53
        />
54
      </LayoutContent>
55
      <LayoutFooter className={styles.footer}>
56
        <Footer />
57
      </LayoutFooter>
58
    </Layout>
59
  );
60
}

1
// src/components/Experience.tsx
2
import React, { useState } from 'react';
3
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
4
import { ExperienceRoot } from '@contentful/experiences-sdk-react';
5
import { PrefetchedProductProvider } from './ProductProvider';
6
import { ProductData } from '../../../services/pim';
7
8
interface ExperienceProps {
9
  experienceJSON: string | null;
10
  locale: string;
11
  /** Pre-fetched products from the server side */
12
  products: Record<string, ProductData>;
13
}
14
15
const Experience: React.FC<ExperienceProps> = ({
16
  experienceJSON,
17
  locale,
18
  products,
19
}) => {
20
  const [queryClient] = useState(() => new QueryClient());
21
22
  return (
23
    <QueryClientProvider client={queryClient}>
24
      <PrefetchedProductProvider products={products}>
25
        <ExperienceRoot experience={experienceJSON} locale={locale} />
26
      </PrefetchedProductProvider>
27
    </QueryClientProvider>
28
  );
29
};

1
// src/studio-config.ts
2
import { defineComponents } from '@contentful/experiences-sdk-react';
3
4
defineComponents([PriceComponentRegistration, ProductComponentRegistration]);