Documentation

Backend compatibility with Node.js 18

Learn how to make the backend of your commercetools Frontend project compatible with Node.js 18.

Copy for LLM
View as Markdown

commercetools Frontend projects are created to be compatible with Node.js 18. However, your existing project may not be compatible with it. In such case, follow the instructions on this page to migrate your project's backend to Node.js 18.x.

In addition to supporting Node.js 18.x, the following process also replaces webpack with tsup, which is built on esbuild, and it is faster and simpler to use. This reduces configuration to a single file, installation to a single package, and build time from around 22 seconds to around 1 second.

Make backend compatible with Node.js 18

Follow these steps to make your webpack-built Node.js 12.x-16.x project compatible with Node.js 18.x:

  1. Remove the webpack-related configuration by deleting the webpack folder at this path packages/PROJECT_NAME/backend/webpack.
  2. Delete the webpack-related packages by running the following command in the packages/PROJECT_NAME/backend directory: yarn remove webpack webpack-cli webpack-merge ts-loader babel-loader dotenv-webpack.
    Also, delete any other packages you added for your webpack configuration. You should install esbuild plugins to replace the packages you deleted.
  3. Add tsup version 7.2.0 by running the following command in the packages/PROJECT_NAME/backend directory: yarn add -D tsup@7.2.0.
  4. Add tsup configuration by adding the following tsup.config.ts file to packages/PROJECT_NAME/backend.
    The tsup.config.ts file to add tsup configurationts
    import { defineConfig } from 'tsup';
import { BuildOptions } from 'esbuild';

export default defineConfig((options) => {
  const dev = options.env?.['NODE_ENV'] === 'dev';
  return {
    entry: ['index.ts'],
    outDir: undefined,
    esbuildOptions: (options: BuildOptions) => {
      options.outfile = 'build/bundle.min.js';
    },
    sourcemap: true,
    watch: dev,
    noExternal: [/(.*)/],
  };
});
  5. Edit the package.json file at this path packages/PROJECT_NAME/backend/package.json as follows:
    • Set the value of engines.node to 16.14 - 18.x.
      18.x is the recommended Node.js version. Using other versions greater than or equal to 16.14 is still supported but not recommended.
      The 16.14 - 18.x range is related to the compatibility of tsup version 7.2.0.
    • Set the value of scripts.extensions:watch to tsup --env.NODE_ENV dev.
    • Set the value of scripts.build to tsup.
    Updated values in the package.json filejson
    {
  ...
  "engines": {
    "node": "16.14 - 18.x"
  },
  "scripts": {
    "extensions:watch": "tsup --env.NODE_ENV dev",
    "build": "tsup",
    ...
  }
}

Caveats and potential issues

Compilation error in Contentful

Some projects were created with versions of Contentful that have issues in their types, specifically version 9.3.5.
If you experience any issues, check Contentful version in the yarn.lock file at this path packages/PROJECT_NAME/backend/yarn.lock or by running the yarn why contentful command:

Compilation error in string-width, strip-ansi, or wrap-ansi

Some projects were created with a deep dependency of the string-width, strip-ansi, or wrap-ansi packages that causes errors during compilation. This can manifest as an error in one of the mentioned packages.
If you experience any issues, add the following resolutions to the package.json file at this path packages/PROJECT_NAME/backend/package.json.
Add resolutions to the package.json filejson
"resolutions": {
  "string-width": "4.2.2",
  "strip-ansi": "6.0.1",
  "wrap-ansi": "7.0.0"
}