API Reference

A reference to the API specification for the @front-commerce/prismic package.

Core API

prismic()

The main function to initialize the Prismic extension in your Front-Commerce application.

front-commerce.config.ts

import prismic from "@front-commerce/prismic";

export default {
  extensions: [prismic()],
};

Integration Fields

The Prismic module provides two main ways to implement Integration Fields:

IntegrationField

A class to create custom integration fields with full control over data fetching and transformation.

import { IntegrationField } from "@front-commerce/prismic";

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,
      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
  autoPaginate: true,
});

Configuration Options:

• loadPullResults: Function to fetch and format data for Prismic
  • Parameters:
    • page: Current page number
    • shopUrl: Base URL of the shop
  • Returns: Promise or direct value of IntegrationFieldApiResponse
• resolveEntity: Function to resolve the entity from blob data
  • Parameters:
    • blob: The blob data stored in Prismic
    • context: GraphQL context with loaders
  • Returns: Promise of the resolved entity or null
• autoPaginate: Boolean to control automatic pagination (defaults to true)

See: Adding Integration Fields for implementation examples.

SitemapIntegrationField

A class to create integration fields that leverage your existing sitemap data.

import { SitemapIntegrationField } from "@front-commerce/prismic";

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);
  },
});

Configuration Options:

• sitemapFetcher: Name of the sitemap fetcher to use
• convertSitemapEntry: Function to convert sitemap entries to Prismic format
  • Parameters:
    • entry: The sitemap entry with data
    • shopUrl: Base URL of the shop
  • Returns: Integration field entry without blob or null
• resolveEntity: Function to resolve the entity from blob data
  • Parameters:
    • blob: The blob data stored in Prismic
    • context: GraphQL context with loaders
  • Returns: Promise of the resolved entity or null

See: Adding Integration Fields for implementation examples.

Content Loading

The Prismic module provides several methods to load content from your Prismic repository:

loadSingle(typeIdentifier)

Loads a single document of a specific type.

const homepage = await loaders.Prismic.loadSingle("homepage");

See: Loading Prismic Content for usage examples.

loadByUID(typeIdentifier, uid)

Loads a document by its Unique ID (UID).

const article = await loaders.Prismic.loadByUID("article", "my-article-slug");

See: Loading Prismic Content for usage examples.

loadByID(id)

Loads a document by its ID.

const document = await loaders.Prismic.loadByID("XYZ123");

See: Loading Prismic Content for usage examples.

loadList(query)

Loads a list of documents matching specific criteria.

const ListQuery = loaders.Prismic.queries.ListQuery;
const query = new ListQuery(10, 1) // pageSize, page
  .type("article")
  .sortBy("document.last_publication_date", "desc");

const articles = await loaders.Prismic.loadList(query);

See: Loading Prismic Content for usage examples.

Content Transformers

The Prismic module provides several transformers to convert Prismic field values into more usable formats:

• TitleTransformer: Transforms Prismic Title fields
• RichtextToWysiwygTransformer: Transforms Rich Text fields to Wysiwyg format
• ImageTransformer: Transforms Image fields with support for views
• LinkTransformer: Transforms Link fields with support for local URL rewriting
• IntegrationFieldTransformer: Transforms Integration Field references

Example usage:

const { RichtextToWysiwygTransformer, ImageTransformer } =
  loaders.Prismic.transformers;

loaders.Prismic.defineContentTransformers("my-type", {
  fieldTransformers: {
    content: new RichtextToWysiwygTransformer(loaders.Wysiwyg),
    image: new ImageTransformer(),
  },
});

See: Loading Prismic Content for more examples of using transformers.

X-Ray Support

The Prismic module provides built-in support for Front-Commerce's X-Ray feature through metadata extractors.

createPrismicMetadataExtractor()

Creates a metadata extractor for enabling X-Ray support on Prismic content.

import { createPrismicMetadataExtractor } from "@front-commerce/prismic";

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

// For types with dynamic identifiers (e.g., using UIDs)
const BlogPostExtractor = createPrismicMetadataExtractor(
  "PrismicBlogPost",
  (data) => data.uid // Function to extract identifier
);

// For Prismic Slices
const SliceExtractor = createPrismicMetadataExtractor(
  "PrismicSlice",
  (content, source) => source.documentMetadata.sliceID ?? ""
);

Parameters:

• extractorIdentifier: The identifier string used to match Prismic content with GraphQL types via the @storefrontContent directive
• identifierValue: Either a static string identifier or a function to extract the identifier from the content
  • If string: Used as-is (good for single types)
  • If function: Called with (fieldData, source) to compute the identifier dynamically

The extractor automatically:

• Generates edit URLs for Prismic's writing room
• Handles both document and slice-level content
• Integrates with Front-Commerce's X-Ray UI

See: Using X-Ray with Prismic for implementation examples.

Types

Core Types

The module exports several TypeScript types for type safety:

import type {
  // The prismic client defined in the dependency injection
  PrismicClient,
  // The integration field type
  IntegrationField,
  // The sitemap integration field type
  SitemapIntegrationField,
  // The metadata extractor type
  PrismicMetadataExtractor,
} from "@front-commerce/prismic";

GraphQL Types

The module also exports types specific to GraphQL integration:

import type {
  // The main Prismic loader type
  PrismicLoader,
  // Available content transformers
  Transformers,
  // Options for configuring content transformers
  ContentTransformOptions,
  // Type definitions for Prismic loaders
  PrismicLoaders,
} from "@front-commerce/prismic/graphql";

Resolver Cache API

See: Using Resolver Cache for implementation examples.

PrismicCachedResolver(resolver, options?)

A higher-order resolver that caches Prismic content at the resolver level. It automatically handles cache invalidation based on Prismic document references.

import { PrismicCachedResolver } from "@front-commerce/prismic/graphql";

const cachedResolver = PrismicCachedResolver(originalResolver, {
  mapParamsToId: (source, args, context) => args.slug,
  contentProperty: "data",
});

Parameters:

• resolver: The original resolver function that returns Prismic content
• options: Optional configuration object
  • mapParamsToId: Function to generate a unique cache key from resolver parameters
  • contentProperty: String indicating which property contains the Prismic content (for nested results)

Returns:

A new resolver function that caches its results based on Prismic document references.

Cache Types:

The resolver supports three types of caching:

• singleton: For single document results
• list: For arrays of documents
• null: For explicitly cached null results using NullContent

NullContent(contentOrDocumentId)

A utility class for caching null results while maintaining Prismic document references.

import { NullContent } from "@front-commerce/prismic/graphql";

const resolver = PrismicCachedResolver((parent, args, { loaders }) => {
  const content = await loaders.Prismic.loadByUID("page", args.uid);
  return content ? content : new NullContent(args.uid);
});

Parameters:

• contentOrDocumentId: Either a Prismic Content object or a document ID string

Returns:

A NullContent instance that can be cached by PrismicCachedResolver.