3.16 -> 3.17

This page lists the highlights for upgrading a project from Front-Commerce 3.16 to 3.17

Update dependencies

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

pnpm update "@front-commerce/*@3.17.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.

pnpm run front-commerce migrate --transform 3.17.0

Manual Migration

Node 24 compatibility

In this version, we have made sure that Front-Commerce is fully compatible with Node 24.

What changed:

Due to certain incompatibilities with some development dependencies, you will require to run React tests using the happy-dom environment, because jsdom doesn't expose the native AbortSignal API from node.

See https://github.com/vitest-dev/vitest/issues/7070.

Migration step:

Update your vitest.config.ts file to use the happy-dom environment:

import { defineProject, mergeConfig } from "vitest/config";
import sharedConfig from "../../vitest.shared";

export default mergeConfig(
  sharedConfig,
  defineProject({
    // ...
    test: {
      environment: "happy-dom",
      // ...
    },
    // ...
  })
);

If your module has both React and non-React tests, you will need to update your vitest.config.ts file to use the happy-dom environment only for the React tests:

import { defineProject, mergeConfig } from "vitest/config";
import sharedConfig from "../../vitest.shared";

export default mergeConfig(
  sharedConfig,
  defineProject({
    test: {
      environmentMatchGlobs: [
        ["**/theme/**/__tests__/**", "happy-dom"],
        ["**/!(theme)/**", "jsdom"],
      ],
    },
  })
);

Minimum supported Node.js version

Front-Commerce 3.17 also raises the minimum supported Node.js runtime to 20.19.0, so be sure to upgrade your local and CI environments before continuing with the migration.

Additional payment information registration

In this update, we have added the automatic registration of additional payment information components. To do this, we have modified the getAdditionalDataComponent and getAdditionalActionComponent functions to register the components automatically.

If you have overridden the getAdditionalDataComponent.js and/or getAdditionalActionComponent.js files, you need to update your implementation.

If you have followed the documentation for registering additional payment information components, you can simply remove your getAdditionalDataComponent.js and/or getAdditionalActionComponent.js files.

But if you have used custom components, you need to update your implementation.

my-extension/index.ts

export default defineExtension({
  name: "my-extension",
  ...
  unstable_lifecycleHooks: {
    onContentCompositionInit: (composition) => {
      composition.register("PaymentAdditionalData", [
        {
          name: "<payment-method-code>",
          client: {
            component: new URL(
              "path/to/my-component.tsx",
              import.meta.url,
            ),
            fragment: null, // if you have a fragment, you can add it here
          },
        },
        {
          name: "action_<payment-method-code>",
          client: {
            component: new URL(
              "path/to/my-action-component.tsx",
              import.meta.url,
            ),
            fragment: null, // if you have a fragment, you can add it here
          },
        },
      ]);
    },
  },
});

Then, you should be able to remove the getAdditionalDataComponent.js and/or getAdditionalActionComponent.js files from your extension.

Override @whatwg-node/promise-helpers dependency

You need to add a pnpm override for @whatwg-node/promise-helpers to ensure compatibility with the current version of Front-Commerce. This override pins the package to version 1.2.5 to prevent issues with newer versions.

Add the following to your package.json under the pnpm section:

{
  "pnpm": {
    "overrides": {
      "@whatwg-node/promise-helpers": "1.2.5"
    }
  }
}

If you already have an overrides section in your pnpm configuration, simply add the @whatwg-node/promise-helpers entry to it.

Facet reset fixes in useLayoutFacets

If you have overridden the useLayoutFacets.js hook from the theme-chocolatine package, you need to update your implementation to fix facet reset functionality.

What changed:

The onReset and onResetAll functions now properly handle form submissions by:

1. Specifying the current route as the form action to prevent unwanted redirects
2. Deleting both regular field names and their array notation variants (fieldName[])

Migration steps:

1. Update the onReset function to delete array notation fields and specify the action:

  const onReset = (names) => {
    return (event) => {
      // ... validation code ...
      const formData = new FormData(event.currentTarget.form);
      for (const name of names) {
        formData.delete(`${name}`);
+       formData.delete(`${name}[]`);
      }
      event.currentTarget.form.reset();
-     submit(formData, { method: "get" });
+     submit(formData, { method: "get", action: location.pathname });
    };
  };

2. Update the onResetAll function to specify the action:

  const onResetAll = () => {
    const formData = new FormData();
    formData.set("sort", currentFacetValues.sort);
    formData.set("pageLength", currentFacetValues.pageLength);
-   submit(formData);
+   submit(formData, { method: "get", action: location.pathname });
  };

These changes ensure that resetting facets removes all filter parameters from the URL and stays on the current page.

Fixes to cart item update modal

In this update, we have fixed an issue with the cart item update modal not closing after the item was successfully updated.

What changed:

The cart item update modal now closes after the item was successfully updated.

Migration steps:

1. Update the CartItemOptionsUpdater to pass the new onSuccessprop to theCartItemOptionsUpdaterModalContent` component.

theme/modules/Cart/CartItem/CartItemOptionsUpdater/CartItemOptionsUpdater.jsx

        <CartItemOptionsUpdaterModalContent
          currentOptions={currentOptions}
          customOptions={customOptions}
          product={product}
          qty={qty}
          item_id={item_id}
+         onSuccess={onToggle}
        />

2. Update the CartItemOptionsUpdaterModalContent component to close the modal after the item was successfully updated.

theme/modules/Cart/CartItem/CartItemOptionsUpdater/CartItemOptionsUpdaterModalContent.jsx

const CartItemOptionsUpdaterModalContent = ({
  currentOptions,
  customOptions = [],
  product,
  qty,
  item_id,
+ onSuccess,
}) => {

  // ...

+ useEffect(() => {
+   if (success) {
+     onSuccess?.();
+   }
+ }, [success]);

  // ...

};

CartItemOptionsUpdaterModalContent.propTypes = {
  qty: PropTypes.number.isRequired,
  item_id: PropTypes.string.isRequired,
  currentOptions: PropTypes.array,
  customOptions: PropTypes.array,
+ onSuccess: PropTypes.func,
  product: PropTypes.object.isRequired,
};

export default CartItemOptionsUpdaterModalContent;

3. Update the useUpdateCartItemOptions to fix the success prop.

theme/modules/Cart/CartItem/CartItemOptionsUpdater/useUpdateCartItemOptions.ts

  return {
    cartItemUpdateSubmissionState: fetcher.state,
-   success: fetcher.data?.error,
+   success: fetcher.data?.success,
    updateCartItemOptions,
  };

Prettier update and rule changes

Upgrading to Prettier version 3.6.2 brought updates to the standard formatting rules, resulting in noticeable changes to how our code is automatically formatted. As a result, we reviewed and updated the codebase to ensure consistency with these new formatting rules, so that all files now conform to Prettier's latest standards.

What changed:

There are two main changes that you need to be aware of:

1. The trailingComma value is now set to all by default (previous value was es5).
2. All methods from the Prettier API are now async.

Migration steps:

1. To cope with the new formatting rules, you will have to run prettier on your codebase, to ensure that diffs between Front-Commerce and your codebase are minimal.
2. If your code used prettier API, you will have to its usage to be async. For example:

- prettier.format(source, { parser: "babel-ts" });
+ await prettier.format(source, { parser: "babel-ts" });

You can see all breaking changes that Prettier version 3 brought on Prettier changelogs

Storybook migration

In this update, we have migrated Storybook from version 8 to version 10. This migration is automated by the codemod.

What changed:

• The @storybook/react package has been replaced with @storybook/react-vite.
• The @storybook/preview-api package has been replaced with storybook/preview-api.
• The @storybook/test package has been replaced with storybook/test.
• The .storybook/main.ts file has been updated.
• The .storybook/preview.tsx file has been updated.
• The package.json file has been updated.

If you have modified .storybook/main.ts or .storybook/preview.tsx, or you have added Storybook addons, please take a look at the Storybook migration guide from version 8 to version 9 and the Storybook migration guide from version 9 to version 10 to update your implementation.