3.7 -> 3.8

This page lists the highlights for upgrading a project from Front-Commerce 3.7 to 3.8

Update dependencies

Update all your @front-commerce/* dependencies to this version:

pnpm update "@front-commerce/*@3.8.0"

Automated Migration

We provide a codemod to automatically update your codebase to the latest version of Front-Commerce. This tool will update your code when possible and flag the places where you need to manually update your code (with // TODO Codemod comments).

pnpm run front-commerce migrate --transform 3.8.0

pnpm run front-commerce migrate --transform 3.8.1

Manual Migration

Category SEO Metadata Generation Function

A new generateCategorySeoMetas function has been added to the theme/modules/Category/CategorySeo directory. This function extracts the logic previously used in the routes/_main.category.$id.tsx route.

If you have overridden the routes/_main.category.$id.tsx route in your project, we recommend updating it to utilize this new function for improved consistency and maintainability.

/media routes have been updated in Magento1 and Magento2 packages

In this release, we fixed the /media routes so that they honors the FRONT_COMMERCE_BACKEND_IGNORE_CACHE_REGEX configuration.

To cope with this update, you should ensure that your codebase contains the changes from the fix if your project overrode /media routes. See the related commit: b445161a.

Update PWA manifest link

In this release, we have fixed an issue with PWA link when the manifest is behind a Basic auth, to fix this in your project, you must apply the following change:

app/root.tsx

export const links: LinksFunction = () => {
-  return [{ rel: "manifest", href: "/manifest.webmanifest" }].concat(
-    pwaAssetsHead.links
-  );
+  return [
+    {
+      rel: "manifest",
+      href: "/manifest.webmanifest",
+      crossOrigin: "use-credentials",
+    },
+  ].concat(pwaAssetsHead.links);
};

You can also check this commit : 35d3bb2f

@front-commerce/remix no longer depends on @opentelemetry/instrumentation

In previous patch releases, we added @opentelemetry/instrumentation as a peer dependency of the @front-commerce/remix package to resolve an issue with how vite bundles the OTel package in production. Since then, we have completely refactored how the metrics middleware integrates with the server.

As a result of this refactoring, the @opentelemetry/instrumentation package is no longer necessary. If you have installed this package in your project, you can safely remove it starting from Front-Commerce 3.8.

To remove the package, run the following command:

pnpm remove @opentelemetry/instrumentation

server.mjs entrypoint changes

This guide outlines important changes to the server.mjs file in Front-Commerce 3.8. These updates improve server initialization and add metrics collection capabilities.

important

These changes are only relevant if you are not using the provided startExpressServer function to start your express server.

For a complete overview of all changes, please refer to the full diff.

onServerInit Hook (Required)

Purpose

The onServerInit hook now receives the GlobalServices instance, allowing to initiate the global services earlier in the server lifecycle.

Implementation

server.mjs

const { frontCommerceConfig } = await getFrontCommerceConfigModule();
const { frontCommerceConfig, services } = await getFrontCommerceConfigModule();
frontCommerceConfig.lifecycleHooks.onServerInit(services.global);

// ... (rest of the code remains the same)

if (viteDevServer) {
  viteDevServer.watcher.on("change", async (file) => {
    // ... (rest of the code remains the same)

    const { frontCommerceConfig: updatedFrontCommerceConfig } =
      await getFrontCommerceConfigModule();
    const {
      frontCommerceConfig: updatedFrontCommerceConfig,
      services: updatedServices,
    } = await getFrontCommerceConfigModule();

    frontCommerceConfig.lifecycleHooks.onServerInit(updatedServices.global);

    const updatedBuild = await getBuildFunction();

    reloadRequestHandler({
      frontCommerceConfig: updatedFrontCommerceConfig,
      services: updatedServices,
      build: updatedBuild,
    });
  });
}

Metrics Middleware (Optional)

Purpose

Collect performance metrics for your application using the new metrics middleware.

Implementation

server.mjs

import {
  installInstrumentation,
  getInstrumentationMeticsKey,
  createMetricsMiddleware,
} from "@front-commerce/remix/server/express/instrumentation";

// ensure that this is done after all `imports` and before any code execution.
const instrumentation = await installInstrumentation();
installGlobals();

const { frontCommerceConfig, services } = await getFrontCommerceConfigModule();
frontCommerceConfig.lifecycleHooks.onServerInit(services.global);

const metricsKey = getInstrumentationMeticsKey(frontCommerceConfig);
if (metricsKey) {
  instrumentation.start(services.global.MetricsService);
}

// ... (rest of the code remains the same)

if (viteDevServer) {
  viteDevServer.watcher.on("change", async (file) => {
    // ... (rest of the code remains the same)

    const {
      frontCommerceConfig: updatedFrontCommerceConfig,
      services: updatedServices,
    } = await getFrontCommerceConfigModule();

    frontCommerceConfig.lifecycleHooks.onServerInit(updatedServices.global);

    const updatedMetricsKey = getInstrumentationMeticsKey(
      updatedFrontCommerceConfig
    );
    if (updatedMetricsKey) {
      instrumentation.start(updatedServices.global.MetricsService);
    } else if (instrumentation.enabled) {
      instrumentation.stop();
    }

    const updatedBuild = await getBuildFunction();

    reloadRequestHandler({
      frontCommerceConfig: updatedFrontCommerceConfig,
      services: updatedServices,
      build: updatedBuild,
    });
  });
}

// ... (rest of the code remains the same)

export const startExpressServer = () => {
  // ... (rest of the code remains the same)

  app.use(express.static("build/client", { maxAge: "1h" }));

  app.use(morgan("tiny"));

  const metricsKey = getInstrumentationMeticsKey(frontCommerceConfig);
  if (metricsKey) {
    app.use(
      createMetricsMiddleware({
        cloudMetricsKey: metricsKey,
      })
    );
  }

  // ... (rest of the code remains the same)

  return app;
};

Root Error Boundary

In this release, we introduced a new RootErrorBoundary component to handle route errors in Remix. Please ensure that you update your projects root.tsx file to export this new component in the ErrorBoundary export.

app/root.tsx

import { RootErrorBoundary } from "theme/pages/Error";

//...

export function ErrorBoundary() {
  //...
}
export const ErrorBoundary = RootErrorBoundary;

To learn more about route error customizations, please refer to the Error Handling for routes guide.