Version: next

Prismic Migration

This page guides you through the migration for breaking changes in the Prismic extension for Front-Commerce v3.

This guide will help you migrate your Prismic features from Front-Commerce v2 to v3. We'll cover the major breaking changes and provide step-by-step instructions for each migration task.

Integration Fields Migration

In Front-Commerce v3, the way to define and register integration fields has been completely revamped to provide a more type-safe and maintainable approach.

V2: Integration Fields (Before)

In v2, integration fields were registered using the Prismic Loader, for example:

server/modules/prismic-demo/index.js
export default {
  namespace: "Demo/Prismic",
  dependencies: ["Prismic/Core"],
  contextEnhancer: ({ req, loaders }) => {
    const { SitemapableIntegrationField } = loaders.Prismic.integrationFields;

    const registerIntegrationField = (name, loader) => {
      const integrationField = new SitemapableIntegrationField(
        name,
        loaders.Sitemap,
        loader
      );
      loaders.Prismic.registerIntegrationField(name, integrationField);
    };

    registerIntegrationField("Product", ({ id }) => {
      return loaders.Product.load(id);
    });

    registerIntegrationField("Category", ({ id }) => {
      return loaders.Category.load(id);
    });
  },
};

V3: Integration Fields (After)

In v3, integration fields are defined as separate classes using either IntegrationField or SitemapIntegrationField, and registered in your extension's lifecycle hooks:

First, create your integration field definitions:

my-extension/integration-fields/product.ts
import { SitemapIntegrationField } from "@front-commerce/prismic";
import type { Product } from "../types";

export const ProductIntegrationField = new SitemapIntegrationField<
  MagentoSitemapProduct,
  Product
>({
  sitemapFetcher: "products",
  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(),
    };
  },
  resolveEntity: (blob, context) => {
    return context.loaders.Product.load(blob.id);
  },
});

Then register them in your extension:

my-extension/index.ts
export default function prismicDemo() {
  return defineRemixExtension({
    // ... other config
    unstable_lifecycleHooks: {
      afterServerServicesInit: async (services, request, config, user) => {
        const { integrationFields } = services.DI.get("prismic");

        integrationFields.registerSitemapField(
          "Product",
          ProductIntegrationField
        );
        integrationFields.registerSitemapField(
          "Category",
          CategoryIntegrationField
        );
      },
    },
  });
}

Additional Resources

Slice Library Migration

Front-Commerce v3 introduces a new Content Composition API that replaces the previous slice library approach, providing better TypeScript support and a more modular structure.

V2: Slice Library (Before)

In v2, slices were defined using a slice library approach:

// theme/modules/Slices/Shared/index.js
import makeSliceLibrary from "theme/modules/Prismic/Slices/makeSliceLibrary";

const sliceLibrary = makeSliceLibrary("SharedSlice", [
  { component: Push, fragment: PushFragment },
  { component: FeaturedProducts, fragment: FeaturedProductsFragment },
  { component: Carousel, fragment: CarouselFragment },
  // ... other slices
]);

export const definitions = sliceLibrary.fragmentDefinitions;
export default sliceLibrary.SliceZone;

V3: Content Composition (After)

In v3, slices are defined using the Content Composition API:

See the Content Composition Guide for more details.

Create your content composition:

// slices/HomePageSlice.ts
import { createContentComposition } from "@front-commerce/core";

export const HomePageSliceComposition = createContentComposition(
  "HomePageSlice",
  [
    {
      name: "Carousel",
      client: {
        component: new URL("./components/Carousel.tsx", import.meta.url),
        fragment: /* GraphQL */ `
          fragment CarouselFragment on Carousel {
            slides {
              title
              image
              cta {
                url
                text
              }
            }
          }
        `,
      },
    },
    // ... other slices
  ]
);

Register the composition in your extension:

// index.ts
export default function prismicDemo() {
  return defineRemixExtension({
    // ... other config
    unstable_lifecycleHooks: {
      onContentCompositionInit: (composition) => {
        composition.registerComposition(HomePageSliceComposition);
      },
    },
  });
}

Additional Resources

Removal of `PrismicPreview` component

In Front-Commerce v2, when using Prismic Previews, you needed to manually add the PrismicPreview component to your application's layout. This is no longer necessary in v3, as the Prismic extension now includes an improved preview toolbar by default. If you keep the PrismicPreview component in your v3 application, it will cause duplicate toolbars to appear.

Integration Fields Migration​

V2: Integration Fields (Before)​

V3: Integration Fields (After)​

Additional Resources​

Slice Library Migration​

V2: Slice Library (Before)​

V3: Content Composition (After)​

Additional Resources​

Removal of PrismicPreview component​

Integration Fields Migration

V2: Integration Fields (Before)

V3: Integration Fields (After)

Additional Resources

Slice Library Migration

V2: Slice Library (Before)

V3: Content Composition (After)

Additional Resources

Removal of `PrismicPreview` component