# Backend compatibility with Node.js 18

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

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](https://www.npmjs.com/package/tsup), which is built on [esbuild](https://esbuild.github.io/), 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](https://github.com/esbuild/community-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`.

   ```ts title="The tsup.config.ts file to add tsup configuration"
   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`.

   ```json title="Updated values in the package.json file"
   {
     ...
     "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:

- If the version is not `9.2.5`, install Contentful version `9.2.5` by running the `run yarn add contentful@9.2.5` command or by editing the version in the `yarn.lock` file.
- If version is `9.2.5`, contact the [commercetools support team](https://support.commercetools.com/).

### 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`.

```json title="Add resolutions to the package.json file"
"resolutions": {
  "string-width": "4.2.2",
  "strip-ansi": "6.0.1",
  "wrap-ansi": "7.0.0"
}
```

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Previous page: Node.js version support plan](/frontend-development/node-version-support.md)
- [Next page: Set up a custom Git repository](/frontend-development/set-up-custom-repository.md)
- [Search documentation and API specs](/search.md)