Version: 3.x

Adding Integration Fields

Learn how to create and use Prismic Integration Fields to connect your Front-Commerce data with Prismic CMS, enabling content managers to seamlessly reference your application's data in their content.

What are Integration Fields?

Integration fields are a Prismic feature that allows content managers to reference external data in their content. In Front-Commerce, this means they can select products, categories, or any other data from your application directly in the Prismic writing room.

Key benefits:

Content managers can build landing pages with real product data without leaving Prismic
Developers can access the referenced data through GraphQL, reusing existing fragments and components
Changes in your application's data are automatically reflected in Prismic

Understanding Integration Fields

Front-Commerce provides two main ways to implement Integration Fields:

Custom Integration Fields

The IntegrationField class is the foundation for creating custom integration fields. It allows you to:

Define how to fetch and paginate your data
Transform your data into Prismic's expected format
Add custom metadata through the blob property
Control pagination behavior

interface UserData {
  userId: string;
  name: string;
  email: string;
  updated_at: string;
  avatar_url?: string;
}

const userIntegrationField = new IntegrationField<UserData>({
  // Function to fetch paginated results from your data source
  loadPullResults: async (page, shopUrl) => {
    const users = await fetchUsers(page);

    return {
      result_size: users.total,
      // By default `autoPaginate` is true, so we don't need to paginate manually
      // If you prefer to paginate manually, set `autoPaginate` to false.
      // Prismic is limited to 50 results per page.
      results: users.items.map((user) => ({
        id: user.userId,
        title: user.name,
        description: user.email,
        image_url: user.avatar_url
          ? new URL(user.avatar_url, shopUrl).toString()
          : undefined,
        last_update: new Date(user.updated_at).valueOf(),
        blob: user, // Original data available in resolveEntity
      })),
    };
  },

  // Function to resolve the entity in your GraphQL context
  resolveEntity: (blob, context) => {
    return context.loaders.User.load(blob.userId);
  },

  // Optional: control pagination behavior of results.
  // By default `autoPaginate` is true, so we don't need to paginate manually
  // If you prefer to paginate manually, set `autoPaginate` to false
  autoPaginate: true,
});

Sitemap Integration Fields

The SitemapIntegrationField is a specialized implementation that leverages your existing sitemap data. See our Customize the sitemap guide for details. It's perfect for exposing products, categories, and other URL-based content:

const productIntegrationField = new SitemapIntegrationField<
  MagentoSitemapProduct,
  Product
>({
  // Name of your sitemap fetcher
  sitemapFetcher: "products",

  // Convert sitemap entry to Prismic's format
  convertSitemapEntry: (entry, shopUrl) => {
    if (!entry.data) return null;

    let imageUrl = entry.images?.[0];
    if (imageUrl) {
      imageUrl = new URL(imageUrl, shopUrl).toString();
    }

    return {
      id: entry.data.sku,
      title: entry.data.name,
      description: entry.data.short_description,
      image_url: imageUrl,
      last_update: new Date(entry.data.updated_at).valueOf(),
    };
  },

  // Resolve the entity in your GraphQL context
  resolveEntity: (blob, context) => {
    return context.loaders.Product.load(blob.id);
  },
});

Implementation Guide

Register Your Integration Fields

Here's a complete example of how to implement and register integration fields:

index.ts
product.ts
category.ts

import { defineExtension } from "@front-commerce/core/extension";
import { ProductIntegrationField } from "./integration-fields/product";
import { CategoryIntegrationField } from "./integration-fields/category";

export default defineExtension({
  unstable_lifecycleHooks: {
    afterServerServicesInit: async (services) => {
      const { integrationFields } = services.DI.get("prismic");

      // Register both product and category integration fields
      integrationFields.registerSitemapField(
        "Product",
        ProductIntegrationField
      );
      integrationFields.registerSitemapField(
        "Category",
        CategoryIntegrationField
      );
    },
  },
});

import { SitemapIntegrationField } from "@front-commerce/prismic";
import type { MagentoSitemapProduct } from "@front-commerce/magento1";
import type { Product } from "~/graphql/graphql";

export const ProductIntegrationField = new SitemapIntegrationField<
  MagentoSitemapProduct,
  Product
>({
  sitemapFetcher: "products",
  convertSitemapEntry: (sitemapEntry, shopUrl) => {
    if (!sitemapEntry.data) {
      return null;
    }

    let imageUrl = sitemapEntry.images?.[0];
    if (imageUrl) {
      imageUrl = new URL(imageUrl, shopUrl).toString();
    }
    return {
      id: sitemapEntry.data.sku,
      title: sitemapEntry.data.name,
      description: sitemapEntry.data.short_description,
      image_url: imageUrl,
      last_update: new Date(sitemapEntry.data.updated_at).valueOf(),
    };
  },
  resolveEntity: (blob, context) => {
    return context.loaders.Product.load(blob.id);
  },
});

import { SitemapIntegrationField } from "@front-commerce/prismic";
import type { MagentoSitemapCategory } from "@front-commerce/magento1";
import type { Category } from "~/graphql/graphql";

export const CategoryIntegrationField = new SitemapIntegrationField<
  MagentoSitemapCategory,
  Category
>({
  sitemapFetcher: "category",
  convertSitemapEntry: (sitemapEntry, shopUrl) => {
    if (!sitemapEntry.data) {
      return null;
    }

    let imageUrl = sitemapEntry.images?.[0];
    if (imageUrl) {
      imageUrl = new URL(imageUrl, shopUrl).toString();
    }

    let description = sitemapEntry.data.meta_description;
    if (!description) {
      description = new URL(sitemapEntry.data.route, shopUrl).toString();
    }

    return {
      id: sitemapEntry.data.entity_id,
      title: sitemapEntry.data.name,
      description: description,
      image_url: imageUrl,
      last_update: new Date(sitemapEntry.data.updated_at).valueOf(),
    };
  },
  resolveEntity: (blob, context) => {
    return context.loaders.Category.load(blob.id);
  },
});

Configure in Prismic

Go to Settings > Integration Fields in your Prismic repository
Create a new Custom API Integration Field
Configure the endpoint:
- URL: https://your-store.example.com/prismic/integration/{name}
- Access Token: Your FRONT_COMMERCE_PRISMIC_WEBHOOK_SECRET value

https://my-repository.prismic.io/settings/integrationfields

Integration field creation
form

Add to Your Custom Types

Add the Integration Field to your Prismic Custom Types:

https://my-repository.prismic.io/masks/blog_post.json/

Custom type field from Integration
field

Expose in GraphQL

Define your GraphQL type:

type MyPrismicContent {
  uid: ID
  title: String
  fc_product: Product # References your existing Product type
  fc_category: Category # References your existing Category type
}

Add the transformer:

import { ProductIntegrationField } from "./integration-fields/product";
import { CategoryIntegrationField } from "./integration-fields/category";

export default createGraphQLRuntime({
  contextEnhancer: ({ loaders }) => {
    const { IntegrationFieldTransformer } = loaders.Prismic.transformers;

    loaders.Prismic.defineContentTransformers("my-type", {
      fieldTransformers: {
        fc_product: new IntegrationFieldTransformer(ProductIntegrationField),
        fc_category: new IntegrationFieldTransformer(
          CategoryIntegrationField
        ),
      },
    });

    return {};
  },
});

Create resolvers:

import { ProductIntegrationField } from "./integration-fields/product";
import { CategoryIntegrationField } from "./integration-fields/category";
// This is a helper for the types of the integration fields transformed by the IntegrationFieldTransformer
import { IntegrationFieldResolverContent } from "@front-commerce/prismic/graphql";

export default createGraphQLRuntime({
  contextEnhancer: (context) => {
    // [..]
  },
  resolvers: {
    MyPrismicContent: {
      fc_product: (
        content: IntegrationFieldResolverContent<
          "product",
          typeof ProductIntegrationField
        >
      ) => {
        return content.product.loadValue().catch(() => null);
      },
      fc_category: (
        content: IntegrationFieldResolverContent<
          "category",
          typeof CategoryIntegrationField
        >
      ) => {
        return content.category.loadValue().catch(() => null);
      },
    },
  },
});

Testing Your Integration

You can test your integration field endpoint using curl:

Product
Category

curl --user 'your-webhook-secret:' http://localhost:4000/prismic/integration/Product
curl --user 'your-webhook-secret:' http://localhost:4000/prismic/integration/Product?page=2

curl --user 'your-webhook-secret:' http://localhost:4000/prismic/integration/Category
curl --user 'your-webhook-secret:' http://localhost:4000/prismic/integration/Category?page=2

important

Integration fields are limited to 50 results per page. Implement proper pagination in your loadPullResults method if you have more data.

The Sitemap Integration Field automatically paginates for you.

Troubleshooting

If your integration isn't working:

Enable debug logs with DEBUG=front-commerce:prismic:integration-fields
Verify your endpoint URL and access token
Check the response format matches Prismic's Custom API Format
Ensure your resolvers correctly handle the blob data

Next Steps

Learn how to customize the Prismic WYSIWYG
Explore adding content slices
Understand using the resolver cache

What are Integration Fields?​

Understanding Integration Fields​

Custom Integration Fields​

Sitemap Integration Fields​

Implementation Guide​

Testing Your Integration​

Troubleshooting​

Next Steps​