Version: 3.x

📑 Manual Migration

This manual migration process should be run after the automated migration process, to complete the missing parts, or debug issues in the migration CLI output.

Transitioning to ESM

Starting 3.0, in a effort to modernize the codebase, we transitioned to ESM. This migration allows a better alignment with browsers standards, an improved static analysis, enhanced language features and overall a better consistency in the JavaScript ecosystem. To learn more about it, see:

Updates in your codebase

Updating exports

To cope with this transition, you should check that your code does not use module.exports = or module.exports.someNamedExport = syntax, and replace it with export default or export {} otherwise.

info

On linux-based systems, you can use the grep command on your project to find those occurences:

grep "module.exports" src/ -r

Uses of `__dirname`

__dirname isn't available anymore in ESM. To cope with this change, you will need to replace its usage. For example:

import { dirname } from "path";
import { fileURLToPath } from "url";

const __dirname = dirname(fileURLToPath(import.meta.url));

For more information about alternatives to __dirname, see:

Updates in your dependencies

You may also have issues with some of your project dependencies that are not ESM-compatible.

First of all, we recommend that you check if the dependencies you are using have a newer version that is ESM-compatible. If so, you can update them to the latest version. If it is not the case, we encourage you to reconsider their usage in your project, and remove them if possible or replace them with an ESM-compatible alternative. It also is a sign of a library that is not actively maintained. You can also contribute to the library by opening an issue or a pull request to make it ESM-compatible, of course!

As a last resort, you can adapt your Vite configuration (vite.config.ts) to handle those cases by tweaking the optimization settings. See the Vite documentation for more information. More particularly these pages:

Components

SEO Components

The xxxSeo components (eg: HomeSeo) have been removed in favor of Remix Meta.

If you use SEO components or have overriden Seo components, you need to:

Remove import and usage of the component from your page
Use the meta function with our generateMetas helper to inject your custom metadatas in your Route Module.

Refactor pages to Remix routes

Page Enhancer HOC usually were responsible for data loading in 2.x. As we now embrace Remix Server/Client Model, page enhancers must be removed in favor of Remix route loaders.

You can see an example in the category route file on how the data loading is now used with the loader method.

You need to pay attention to two thing if you've overriden this file :

Did you update the query to fetch category?

We now recommend you to update the GraphQL query used in category route and pass down any new props to the Category component.

Did you added more HOC to the Enhancer?

You can either add your custom HOC to the Category component or replace HOC with hooks if relevant.

`Product` page

In v3, the base theme got completely rid of any HOC, by leveraging on standard mechanics from Remix loaders and hooks:

withTrackPage and withProductTracking responsibilities have been transfered to useTrackPage and useProductPage hooks
Loading state management is done directly at route loader level

`Account` pages

Similarly, page-base HOCs on the Account page have been completely removed, and replaced with standard Remix and React mechanics. Here's a list of all removed Enhancers in those pages:

EnhanceDownloadableProduct (see merge request)
EnhanceAddressBook (see merge request)
EnhanceDashboard (see merge request)

`withTrackOnMount` HOC depreciation

withTrackOnMount has been deprecated in favor of a new hook useTrackOnMount. The new hook has a slightly different signature:

Old prop	New prop	Prop type
isResolvedFromProps	hasResolved	~~`function`~~ → `boolean`
mapPropsToProperties	createProperties	`function`

shouldMountEvent, shouldUpdateEvent and trackEvent have been left unchanged.

// Before (HOC)
withTrackOnMount({
  event: "Product Viewed",
  isResolvedFromProps: (props) => !props.loading && props.product,
  mapPropsToProperties: (props) => {
    const finalPrice = props.product?.prices?.finalPrice?.priceInclTax?.value;
    return {
      sku: props.product.sku,
      name: props.product.name,
      price: finalPrice?.amount,
      currency: finalPrice?.currency,
    };
  },
});

// After (Hook)
useTrackOnMount({
  event: "Product Viewed",
  hasResolved: !props.loading && Boolean(props.product),
  createProperties: () => {
    const finalPrice = props.product?.prices?.finalPrice?.priceInclTax?.value;
    return {
      sku: props.product?.sku,
      name: props.product?.name,
      price: finalPrice?.amount,
      currency: finalPrice?.currency,
    };
  },
});

`withProductTracking` replaced with `useProductTracking`

Similarly, the page-based HOC withProductTracking has been completely removed, in favor of a new useProductTracking hook.

If you used this HOC in your code, you will have to replace it by calling useProductTracking in the component the HOC was previously used on. useProductTracking only takes the product as parameter.

`withProductAddedPopIn` removed

The HOC withProductAddedPopIn has been completely removed, in favor of using a local useState insied the Product component.

If you used this HOC in your code, you will have to replace it by using useState in the component the HOC was previously used on:

import { useState } from "react";
// ...

const MyComponent = () => {
  const [productAdded, setProductAdded] = useState(null);

  // ...

  return (
    <div>
      <ProductAddedPopIn product={productAdded} hidePopin={() => setProductAdded(null)} />

      <ProductView
        onProductAdded={(product) => setProductAdded(product)}
        {/* ... */}
      />
    </div>
  );
}

`withCartTracking` replaced with `useCartTracking`

The page-based HOC withCartTracking has been completely removed, in favor of a new useCartTracking hook.

If you used this HOC in your code, you will have to replace it by calling useCartTracking in the component the HOC was previously used on. useCartTracking only takes the cart as parameter.

`withLogoutMutation` has been removed

The page-based HOC withLogoutMutation has been completely removed, and has been replaced with a /logout route.

If you used this HOC in your code, you can remove it and use a link to /logout instead. See skeleton/app/routes/logout.tsx and theme/pages/Account/Logout/Logout.jsx for examples.

`makeCommandDispatcherWithCommandFeedback` API change

makeCommandDispatcherWithCommandFeedback API has changed. In version 2, the second parameter of makeCommandDispatcherWithCommandFeedback was an optional boolean (default true) and if this parameter was evaluated to a truthy value, the resulting component had the responsibility of displaying the result of the command with the InlineAlert component. In version 3, makeCommandDispatcherWithCommandFeedback now expects an optional React component to display the result of the command.

To cope with this change, you need to review all components using makeCommandDispatcherWithCommandFeedback:

if makeCommandDispatcherWithCommandFeedback is called with a falsy second parameter, you don't have to change anything

if makeCommandDispatcherWithCommandFeedback is called with a truthy second parameter or without the second parameter, you have to adapt your code. To have exactly the same behavior as before, the new call should look like:

makeCommandDispatcherWithCommandFeedback(
  {
    /* commands definition */
  },
  ({ success, message }) => {
    return (
      <InlineAlert appearance={success ? "success" : "error"}>
        {message}
      </InlineAlert>
    );
  }
);

`withEntityNotFound` API change

withEntityNotFound API has changed. In version 2, the parameter NotFoundComponent was optional (defaulted to NotFound component). This HOC is now deprecated and is now in the theme-agnostic @front-commerce/compat package. If you still want to use withEntityNotFound, you must now provide a NotFoundComponent component parameter.

To cope with this change, you need to review all component using withEntityNotFound to make sure a NotFoundComponent parameter is passed to it. For example, by using the component it was previously defaulted to:

import NotFound "theme/modules/PageError/NotFound/NotFound"

/*
  ... your component
*/

export default withEntityNotFound({
    isFound: () => false,
    NotFoundComponent: NotFound,
})(MyComponent);

A even better way would be to get rid of withEntityNotFound, and instead handle this mechanism directly withing the related loader by throwing a 404 response there. For more information about this practice, see Remix's guide on handling 404s.

`PartialProductQuery` removal

In version 3, PartialProductQuery has been completely removed as it is not used by the base theme anymore. If it was used in your project, you will have to replace it with your own query or fragment.

For reference, the query was:

#import "theme/modules/ProductView/ProductItem/ProductItemFragment.gql"

query PartialProductQuery($sku: String!) {
  product(sku: $sku) {
    ...ProductItemFragment
  }
}

Sass Migration

In the latest version of Front-Commerce we converted all global Sass variables to CSS variables during the automated migration. This allows for a more modular approach to theming and a better developer experience. However, there are still some manual steps that need to be taken to complete the migration.

Breakpoints Removal

The following scss helpers have been removed. If you were using them, you have to manually add them back to your project or update implementation

To replace usage of these scss methods

Instead of relying on the removed Sass mixins, we recommend to now use a standardized approach that involves directly using media queries in your CSS code. This approach provides better control, readability, and maintenance of responsive styles.

Here are the breakpoints values we used:

xs: 0
sm: 576px
md: 768px
lg: 992px
xl: 1200px

For each breakpoint where you were previously using the breakpoint-min function, replace it with a media query using the min-width property. For example:

Before:

$min: breakpoint-min("sm");
@media (min-width: $min) {
  // Styles for 'sm' and wider
}

After:

@media (min-width: 576px) {
  // Styles for 'sm' and wider
}

For cases where you were using the media-breakpoint-up, you can use a media query with min-width too. For example:

Before:

@include media-breakpoint-up("md") {
  // Styles for 'md' and wider
}

After:

@media (min-width: 768px) {
  // Styles for 'sm' and wider
}

And you can remove @include media-breakpoint-up("xs") { as it applied CSS rules systematically.

To restore the usage of these scss methods

You can copy it from the v2.x code and add it to a breakpoints override or a custom file, then you should import it in any of your scss files which require either the variable, mixin or function, for example:

theme/components/atoms/Container/Container.scss
@import "theme/components/atoms/Breakpoints/breakpoints";

.container {
  background-color: red;

  @media screen and (min-width: $menuBreakpoint) {
    max-width: 40em;
  }

  @include media-breakpoint-up(sm) {
    background-color: blue;
  }

  @include media-breakpoint-up(md) {
    background-color: green;
  }

  @include media-breakpoint-up(lg) {
    background-color: yellow;
  }
}

info

After running the codemods on your project, you can find these deprecations by searching TODO (Codemod generated) in your project.

Media queries

If you use any media queries which use global sass variables, you need to manually import the file defining the variables.

If you have the following example component, You will need to import the breakpoints.scss file.

theme/components/atoms/Form/Fieldset/Fieldset.scss
@import "theme/components/atoms/Breakpoints/breakpoints";

fieldset {
  border: none;
  font-size: var(--regularSize);
  .fieldset--large {
    max-width: 30em;
    @media screen and (min-width: $menuBreakpoint) {
      max-width: 40em;
    }
  }
}

If you're using the $boxSizeMargin, $smallContainerWidth, or $containerWidth variables you should to import @import "theme/variables"; instead.

info

After running the codemods on your project, you can easily find these occurrences by searching TODO (Codemod generated) in your project.

Color functions

If you use any Sass color functions you will need to directly import the color.scss file at the location where it is used. This is because Sass can not process the functions on CSS variables.

If you have the following example component:

theme/components/atoms/Example/Example.scss
.Example {
  color: darken(var(--colorPrimary), 10%);
}

You would need to import the color.scss directly in the Example.scss file

theme/components/atoms/Example/Example.scss
@import "theme/components/atoms/Colors/colors";

.Example {
  color: darken(var(--colorPrimary), 10%);
  color: darken($colorPrimary, 10%);
}

Calculations

The automated migration step takes care of changing SASS global variables to CSS custom properties and of transforming declarations value with a unique multiplication and the usage of math.div so that it becomes a valid CSS declaration:

theme/components/atoms/Example/Example.scss
.example {
  padding: $boxSizeMargin;
  padding: var(--boxSizeMagin);

  margin-top: $boxSizeMargin * 2;
  margin-top: calc(var(--boxSizeMagin) * 2);

  margin-bottom: math.div($boxSizeMargin, 4);
  margin-bottom: calc(var(--boxSizeMargin) / 4);
}

However for more complex calculations or for declarations with several values, only the usage of the SASS variable will be updated. After this step, a manual fix is needed. When starting Front-Commerce, sass is executed and it will report any invalid expressions. Here is a list of common pattern to fix:

theme/components/atoms/Example/Example.scss
.example {
  padding: var(--boxSizeMargin) * 2 var(--boxSizeMargin) * 4 var(
      --boxSizeMargin
    ) * 2 0;
  padding: calc(var(--boxSizeMargin) * 2) calc(var(--boxSizeMargin) * 4) calc(
      var(--boxSizeMargin) * 2
    ) 0;

  max-width: calc(#{var(--boxSizeMargin) * 24} + 50ch);
  max-width: calc(var(--boxSizeMargin) * 24 + 50ch);

  margin: calc(-var(--boxSizeMargin) / 4) * 3;
  margin: calc(-var(--boxSizeMargin) * 3 / 4);

  padding-left: 1.5rem - calc(var(--boxSizeMargin) / 2);
  padding-left: calc(1.5rem - calc(var(--boxSizeMargin) / 2));

  padding-right: 1.5rem - calc(var(--boxSizeMargin) / 2);
  padding-right: calc(1.5rem - calc(var(--boxSizeMargin) / 2));
}

`@extend` handling

If @extend is used with a selector defined in another stylesheet, you need to manually import that stylesheet. For example, sass would fail compiling the following stylesheet:

theme/components/atoms/Example/Example.scss
.example {
  @extend .another-selector;
}

This is happening because .another-selector is unknown, so the solution is to import the stylesheet defining it:

theme/components/atoms/Example/Example.scss
@import "theme/some/path/defining/another-selector";

.example {
  @extend .another-selector;
}

In V2, a modal state parameter facilitated rendering arbitrary routes in a modal during routing. In Remix, this is non-trivial unless the target route is a child route. We have introduced a ModalLink component to replace the previous mechanism. It generates a link that displays a component in a modal upon user click, with the modal state reflected in the URL hash for sharing and consistent UI presentation across users.

Here is an example of the required changes:

theme/components/organisms/Header/Header.js
import { ModalLink } from "theme/components/organisms/Modal";
import Login from "theme/components/organisms/Login";

export function Header() {
  return (
    <header>
      <Link to={{ pathname: "/whatever", state: { modal: true } }}>Login</Link>
      <ModalLink to="/login" linkContent="Login">
        <Login />
      </ModalLink>
    </header>
  );
}

Environment variables

Front-Commerce

In V3, the FRONT_COMMERCE_DISABLE_OFFLINE_MODE environment variable has been removed completely.

Renamed variables:

V2	V3
`FRONT_COMMERCE_FACEBOOK_CLIENT_ID`	`FRONT_COMMERCE_LOGIN_FACEBOOK_CLIENT_ID`
`FRONT_COMMERCE_FACEBOOK_CLIENT_SECRET`	`FRONT_COMMERCE_LOGIN_FACEBOOK_CLIENT_SECRET`
`FRONT_COMMERCE_GOOGLE_CLIENT_ID`	`FRONT_COMMERCE_LOGIN_GOOGLE_CLIENT_ID`
`FRONT_COMMERCE_GOOGLE_CLIENT_SECRET`	`FRONT_COMMERCE_LOGIN_GOOGLE_CLIENT_SECRET`

Magento

In V2, Magento1 and Magento2 environment variables were prefixed the same way. FRONT_COMMERCE_MAGENTO_*, in V3, we have split them into FRONT_COMMERCE_MAGENTO1_* and FRONT_COMMERCE_MAGENTO2_*.

- FRONT_COMMERCE_MAGENTO_CONSUMER_KEY=token
- FRONT_COMMERCE_MAGENTO_CONSUMER_SECRET=token
- FRONT_COMMERCE_MAGENTO_ACCESS_TOKEN=token
- FRONT_COMMERCE_MAGENTO_ACCESS_TOKEN_SECRET=token

## Magento 1
+ FRONT_COMMERCE_MAGENTO1_CONSUMER_KEY=token
+ FRONT_COMMERCE_MAGENTO1_CONSUMER_SECRET=token
+ FRONT_COMMERCE_MAGENTO1_ACCESS_TOKEN=token
+ FRONT_COMMERCE_MAGENTO1_ACCESS_TOKEN_SECRET=token

## Magento 2
+ FRONT_COMMERCE_MAGENTO2_CONSUMER_KEY=token
+ FRONT_COMMERCE_MAGENTO2_CONSUMER_SECRET=token
+ FRONT_COMMERCE_MAGENTO2_ACCESS_TOKEN=token
+ FRONT_COMMERCE_MAGENTO2_ACCESS_TOKEN_SECRET=token

Other optional variables updated:

2.x	3.x - Magento1	3.x - Magento2
`FRONT_COMMERCE_MAGENTO_ADMIN_PATH`	`FRONT_COMMERCE_MAGENTO1_ADMIN_PATH`	`FRONT_COMMERCE_MAGENTO2_ADMIN_PATH`
`FRONT_COMMERCE_MAGENTO_TIMEOUT`	`FRONT_COMMERCE_MAGENTO1_TIMEOUT`	`FRONT_COMMERCE_MAGENTO2_TIMEOUT`
`FRONT_COMMERCE_MAGENTO_ADMIN_TIMEOUT`	`FRONT_COMMERCE_MAGENTO1_ADMIN_TIMEOUT`	`FRONT_COMMERCE_MAGENTO2_ADMIN_TIMEOUT`
`FRONT_COMMERCE_XRAY_MAGENTO_VERSION`	`FRONT_COMMERCE_XRAY_MAGENTO1_VERSION`	❌ N/A

`makeImageProxyRouter` → `createResizedImageResponse`

The makeImageProxyRouter function has been removed in favor of the new createResizedImageResponse function. You can read more about the implementation details in the createResizedImageResponse documentation.

All images which are located under public/images/resized/* should now be moved to public/images/*. This will allow for the /images/resized/* resource route to be reserved for the new createResizedImageResponse function.

Removal of `SmartLayout` component

In v3 we removed the SmartLayout component. This component was used to enhance the Layout component with navigationMenu for the header and footer.

The Layout component now requires two props headerNavigationMenu and footerNavigationMenu to be passed to it.

This is can be retrieved via a loader: see example in _main.tsx layout

app/routes/_main.tsx
export const loader = async ({ context }: LoaderFunctionArgs) => {
  const app = new FrontCommerceApp(context.frontCommerce);
  const headerResponse = await app.graphql.query(HeaderQueryDocument, {
    name: "data",
  });

  const footerResponse = await app.graphql.query(NavigationMenuDocument, {
    name: "categories",
  });

  return json({
    headerNavigationMenu: headerResponse?.navigationMenu || [],
    footerNavigationMenu: footerResponse?.navigationMenu || [],
  });
};

`react-helmet-async` removal

In version 3, react-helmet-async has been removed as it does not make sense in a remix application. If you used this in any custom components or pages, you will now need to move it the meta function of the route.

Client side log handler removal

The client side log mechanism has been removed from Front-Commerce 3.0. For future version, we plan to bring back this feature. In the meantime, if you are using this feature or you have overridden a component using this feature, you need to remove it. In version 2.x, the API was imported from web/core/logs/logHandler.

`@loadable/component` removal

@loadable/component is no longer a dependency of Front-Commerce. That means components that were previously made loadable are now loaded synchronously as any other component. In terms of usage, in most cases this change should be transparent. That's not the case if you are manually preloading a component with Component.preload() or if you have overridden a file that is doing it. In those case, you have to remove .preload() calls.

In addition, you can still use @loadable/component in your custom components and then you have to make sure @loadable/component is a dependency of your project.

`CartSeo` removal

In version 3, CartSeo has been removed as it is not used by the base theme anymore. If you overrode this component or one using it, you will need to move any of the customisation to the cart route meta function.

`EmptyCart` refactor

The component EmptyCart has been refactored and its HOC EnhanceEmptyCart has been removed to benefit from data served directly from the cart route loader. It is now rendered directly as a page in _main.cart.tsx instead of rendered as a component in Cart. If you have overridden this component in you project, you will need to ensure the changes are compatible with the new version.

See related MR (!2525) for more informations.

Removed `MenuNavigation` component

The component MenuNavigation was only used in the default theme of Front-Commerce, and was subsequently removed in version 3.0 (see related MR)

`react-apollo` usage removed from `theme-chocolatine`

In an effort to remove react-apollo dependency in theme chocolatine, we removed all occurences of graphql(), useQuery() and useLazyQuery() calls in it, and replace them by either direct API calls using remix's useFetcher, or move them to the related route loader when possible. This means a good number of Enhancers have also been reworked, and sometimes removed completely. Here's the list of the Enhancers that have been removed:

EnhanceEmptyCart (see MR): EmptyCart component is now used as a page rendered directly under /cart route
EnhanceCart (see MR) was moved to the /cart route loader
withCountries (see MR): replaced with useCountries hook
EnhanceChoosePayment (see MR): replaced with usePaymentMethods hook
EnhanceHeader (see MR): replaced with useCustomer and useCart
checkCart (see MR): refactor
withCartId (see MR): replaced with withCart
EnhanceMiniCartContent (see MR): replaced with useCart
EnhanceCartRecap (see MR): replaced with useCart
withCheckoutSuccessTracking (see MR): replaced withuseCheckoutSuccessTracking
GscText 's HOC (see MR): replaced with useStore
EnhanceProductReviews (see MR): replaced with useProductReviews
withIsSubscribedToInStockAlert (see MR): replaced with useIsSubscribedToStockAlert
EnhanceSearchBar (see MR): moved logic to useSearchBar

Additionally, some Enhancers and HOCs were modified for the same purpose. If you those were overriden in your project, you will have to check what change and adapt it in your code:

EnhanceChooseShippingMethod (see MR)
EnhanceAddToCart (see MR)
EnhanceAddress (see MR)
withCheckoutTracking (see MR)
EnhanceProductGallery (see MR)
EnhancePublishProductreview and EnhanceLoginForm (see MR)
EnhanceSubscribeToInStockAlert (see MR)
EnhanceCurrencySelector (see MR)
EnhanceAddToCartModal (see MR)

`useDevice()` removal

We removed the useDevice() hook in version 3.0. It was unused in the base theme, and we had no use cases in mind for it.

Device information are still available in the configuration. Access it using config.device. Please contact us if you have a use case we don't support anymore.

Sitemap Changes

Please refer to the the Customize the Sitemap documentation for more details on how to implement dynamic sitemaps in v3.

Sitemap URL change

In v3, the sitemap URL has been changed from /sitemaps/sitemap.xml to /sitemap.xml.

SitemapLoader

The registerNodesFetcher method will no longer work in v3, instead you should register a fetchers via the sitemap service
The overrideNodesFetcher method will no longer work in v3, instead you should override a fetcher via the sitemap service

GraphQL Schema

The Sitemapable GraphQL interface has been deprecated for removal. It can be removed from your project.
The SitemapImage GraphQL type has been deprecated for removal. It can be removed from your project.

Transitioning to ESM​

Updates in your codebase​

Updating exports​

Uses of __dirname​

Updates in your dependencies​

Components​

SEO Components​

Refactor pages to Remix routes​

Product page​

Account pages​

withTrackOnMount HOC depreciation​

withProductTracking replaced with useProductTracking​

withProductAddedPopIn removed​

withCartTracking replaced with useCartTracking​

withLogoutMutation has been removed​

makeCommandDispatcherWithCommandFeedback API change​

withEntityNotFound API change​

PartialProductQuery removal​

Sass Migration​

Breakpoints Removal​

To replace usage of these scss methods

To restore the usage of these scss methods

Media queries​

Color functions​

Calculations​

@extend handling​

Modal Routes​

Environment variables​

Front-Commerce​

Renamed variables:​

Magento​

makeImageProxyRouter → createResizedImageResponse​

Removal of SmartLayout component​

react-helmet-async removal​

Client side log handler removal​

@loadable/component removal​

CartSeo removal​

EmptyCart refactor​

Removed MenuNavigation component​

react-apollo usage removed from theme-chocolatine​

useDevice() removal​

Sitemap Changes​

Sitemap URL change​

SitemapLoader​

GraphQL Schema​

Transitioning to ESM

Updates in your codebase

Updating exports

Uses of `__dirname`

Updates in your dependencies

Components

SEO Components

Refactor pages to Remix routes

`Product` page

`Account` pages

`withTrackOnMount` HOC depreciation

`withProductTracking` replaced with `useProductTracking`

`withProductAddedPopIn` removed

`withCartTracking` replaced with `useCartTracking`

`withLogoutMutation` has been removed

`makeCommandDispatcherWithCommandFeedback` API change

`withEntityNotFound` API change

`PartialProductQuery` removal

Sass Migration

Breakpoints Removal

Media queries

Color functions

Calculations

`@extend` handling

Modal Routes

Environment variables

Front-Commerce

Renamed variables:

Magento

`makeImageProxyRouter` → `createResizedImageResponse`

Removal of `SmartLayout` component

`react-helmet-async` removal

Client side log handler removal

`@loadable/component` removal

`CartSeo` removal

`EmptyCart` refactor

Removed `MenuNavigation` component

`react-apollo` usage removed from `theme-chocolatine`

`useDevice()` removal

Sitemap Changes

Sitemap URL change

SitemapLoader

GraphQL Schema