Version: next

Using X-Ray with Prismic

Learn how to enable X-Ray support for your Prismic content, allowing content editors to quickly access and edit content directly from your storefront.

Overview

The Prismic module provides built-in support for Front-Commerce's X-Ray feature through the PrismicMetadataExtractor. This allows content editors to:

See which parts of the page come from Prismic
Click directly through to edit the content in Prismic
Understand the structure of their content

http://localhost:4000

X-Ray in Prismic

Implementation Steps

Create Metadata Extractors

There are three ways to create metadata extractors in Prismic:

Singleton (static identifier)
Custom Identifier (dynamic identifier)
Document/Slice ID (dynamic identifier)

Singleton
Custom Identifier
Metadata Identifier

A singleton extractor is used for content types that have a static identifier that will not change.

my-extension/extractors/HomePageExtractor.ts
import { createPrismicMetadataExtractor } from "@front-commerce/prismic";

export const HomePageExtractor = createPrismicMetadataExtractor(
  "PrismicHomePage", // The identifier used in @storefrontContent directive
  "home_page" // For single types, use a static identifier
);

A Custom identifier extractor is used for content types that have a dynamic identifier that will change.

my-extension/extractors/BlogPostExtractor.ts
import { createPrismicMetadataExtractor } from "@front-commerce/prismic";

export const BlogPostExtractor = createPrismicMetadataExtractor(
  "PrismicBlogPost",
  (data) => data.uid // Use a function to extract the identifier
);

A metadata identifier extractor is used for content types that have a dynamic identifier that will change.

The documentMetadata will include a sliceID when it has been defined as a slice, otherwise it will only include a documentID.

my-extension/extractors/SliceExtractor.ts
import { createPrismicMetadataExtractor } from "@front-commerce/prismic";

export const SliceExtractor = createPrismicMetadataExtractor(
  "PrismicSlice",
  (content, source) => source.documentMetadata.sliceID ?? ""
);

Update GraphQL Schema

Add the @storefrontContent directive to your types:

type HomePage @storefrontContent(extractorIdentifier: "PrismicHomePage") {
  title: String
  content: DefaultWysiwyg
}

type BlogPost @storefrontContent(extractorIdentifier: "PrismicBlogPost") {
  uid: String!
  title: String
  content: DefaultWysiwyg
}

union SharedSlice = ProductsSlice | FeaturedProductSlice | RichTextSlice

type ProductsSlice @storefrontContent(extractorIdentifier: "PrismicSlice") {
  sliceID: String
  title: String
  products: [Product]
}

type FeaturedProductSlice
  @storefrontContent(extractorIdentifier: "PrismicSlice") {
  sliceID: String
  title: String
  product: Product
}

type RichTextSlice @storefrontContent(extractorIdentifier: "PrismicSlice") {
  sliceID: String
  content: DefaultWysiwyg
}

Register Extractors

my-extension/index.ts
import { defineExtension } from "@front-commerce/core/extension";
import { HomePageExtractor } from "./extractors/HomePageExtractor";
import { BlogPostExtractor } from "./extractors/BlogPostExtractor";
import { SliceExtractor } from "./extractors/SliceExtractor";

export default defineExtension({
  name: "my-module",
  unstable_lifecycleHooks: {
    onServerServicesInit: async (services) => {
      services.ContentMetadataExtractorRegistry.register([
        HomePageExtractor,
        BlogPostExtractor,
        SliceExtractor,
      ]);
    },
  },
});

Implement Slice Resolvers

Resolve sliceID to identify the slice with the correct identifier:

my-extension/runtime.ts
import { createGraphQLRuntime } from "@front-commerce/core/graphql";
import { withSliceFields } from "./extractors/SliceExtractor";

type IntegrationFieldContent<field extends string> = {
  [key in field]: {
    blob: { id: string };
  };
};

// Helper HOF to add sliceID to resolvers
export function withSliceFields<T extends Record<string, any>>(resolvers: T) {
  return {
    sliceID: (content: any) => content.documentMetadata.sliceID,
    ...resolvers,
  };
}

export default createGraphQLRuntime({
  resolvers: {
    // Add sliceID and resolve products for ProductsSlice
    ProductsSlice: withSliceFields({
      title: (content) => content.primary.title,
      products: async (
        content: IntegrationFieldContent<"products">,
        _,
        { loaders }
      ) => {
        return Promise.all(
          content.items.map((item: IntegrationFieldContent<"product">) => {
            return loaders.Product.load(item.product.blob.id);
          })
        ).then((products = []) => products.filter(Boolean));
      },
    }),

    // Add sliceID and resolve single product for FeaturedProductSlice
    FeaturedProductSlice: withSliceFields({
      title: (content) => content.primary.title,
      product: async (
        content: IntegrationFieldContent<"product">,
        _,
        { loaders }
      ) => {
        return loaders.Product.load(content.primary.product.blob.id);
      },
    }),

    // Add sliceID and transform rich text content
    RichTextSlice: withSliceFields({
      content: ({ content }) => content,
    }),
  },
});

The withSliceFields helper:

Automatically adds the sliceID field required for X-Ray
Preserves your existing resolver implementations
Ensures proper typing with TypeScript
Works with any slice type

note

The withSliceFields helper is an example for this guide and not a public API, you can implement your own helper to extract the identifier. To ease reuse across different resolvers or applications, you can relocate as an export from the SliceExtractor.ts module.

Add StorefrontContent Components

Wrap your React components with StorefrontContent:

my-extension/components/HomePage.tsx
import { StorefrontContent } from "theme/modules/StorefrontContent";

export function HomePage({ data }) {
  return (
    <StorefrontContent type="PrismicHomePage" id="home_page" scope="page">
      <h1>{data.title}</h1>
      <div>{data.content}</div>
      {data.slices.map((slice) => (
        <SliceComponent key={slice.sliceID} slice={slice} />
      ))}
    </StorefrontContent>
  );
}

function SliceComponent({ slice }) {
  switch (slice.__typename) {
    case "ProductsSlice":
      return (
        <StorefrontContent type="PrismicSlice" id={slice.sliceID}>
          <h2>{slice.title}</h2>
          <ProductGrid products={slice.products} />
        </StorefrontContent>
      );
    case "FeaturedProductSlice":
      return (
        <StorefrontContent type="PrismicSlice" id={slice.sliceID}>
          <h2>{slice.title}</h2>
          <ProductCard product={slice.product} />
        </StorefrontContent>
      );
    case "RichTextSlice":
      return (
        <StorefrontContent type="PrismicSlice" id={slice.sliceID}>
          <div>{slice.content}</div>
        </StorefrontContent>
      );
    default:
      return null;
  }
}

tip

If you are using the Content Composition API to register your slices, then the above code can be simplified to:

my-extension/components/HomePage.tsx
import { CompositionComponent } from "@front-commerce/core/react";

export function HomePage({ data }) {
  return (
    <StorefrontContent type="PrismicHomePage" id="home_page" scope="page">
      <CompositionComponent
        name="HomePageSlice"
        content={homepage.mainContent}
        renderComponent={(component) => {
          const sliceID = component.props.sliceID;
          if (sliceID) {
            return (
              <div>
                <StorefrontContent type="PrismicSlice" id={sliceID}>
                  {component}
                </StorefrontContent>
              </div>
            );
          }
          return <div>{component}</div>;
        }}
      />
    </StorefrontContent>
  );
}

Also see the Adding content slices documentation for more details.

Testing X-Ray Integration

Start your development server
Enable X-Ray mode using the Magic Button
Verify that:
- Prismic content is highlighted with the Prismic brand color
- Clicking the edit button opens the correct page in Prismic
- Both page-level and block-level content are properly identified
- Slice content shows the correct edit button and links

Overview​

Implementation Steps​

Testing X-Ray Integration​

See Also​

Overview

Implementation Steps

Testing X-Ray Integration

See Also