With the Node builder update to version 7.x, IO apps using this builder benefit from the Node.js 20 engine and TypeScript 5.x libraries, improving performance and security. It also means these apps need to be adjusted for the latest features.

To update your app to use the new builder version, follow the instructions below:

1. Update the VTEX IO CLI to version 4.1.0 or newer.

   1. In a terminal, run vtex -v to check your VTEX IO CLI version. If you do not have VTEX IO CLI installed, see the instructions in Installing VTEX IO CLI.
   2. If your version is older than 4.1.0, run vtex autoupdate to update your VTEX IO CLI.

2. Make sure node/package.json has the typescript property in devDependencies. 3. In your app folder, open the node/package.json file. 4. In the devDependencies property, verify if the typescript package is declared. If not, add it with version 5.x. It should look like this:

   node/package.json

   
   

   _10

   "devDependencies": {

   _10

   ...

   _10

   "typescript": "5.x"

   _10

   },

   
   

   If the app already has typescript declared in devDependencies, you do not need to change its version manually. When linking the app, the package version is overwritten automatically.

3. Update the manifest.json with node 7.x.

   1. In your app folder, open the manifest.json file.

   2. Change the node builder version to 7.x. It should look like this:

      manifest.json

      
      

      _10

      "builders": {

      _10

      ...

      _10

      "node": "7.x"

      _10

      },

      
      

4. Test the app.

   1. Open a terminal in the root folder of your app.
   2. Make sure you are in a development workspace. You can create a new one or switch to an existing one.
   3. Run vtex link. You will notice that the node/package.json will be updated with the new versions of typescript (5.5.3) and @node/types (20.x).
   4. Verify errors and fix them if they appear. Your app might not be fully compatible with the newer TypeScript and Node.js engine versions, and syntax, typing, or dependency errors might happen. See the Troubleshooting section for instructions about the most common errors.

5. Create and deploy a new app version, following the steps in Deploying a new app version.

   1. In the Release a new app version step, we recommend creating a minor version since this is not exclusively fixing issues as in a patch, and a major would require additional work.

      For apps in the App Store, creating a new major will require the app to go through the homologation process.

   2. Follow the other steps (Publish, Test, Deploy, and Promote) according to your scenario. Some apps are used only on one account, and others should deploy the new version to other accounts.

If you need help migrating your app to the Node builder 7.x, open a ticket with VTEX Support.

When migrating your app to the new builder version, some issues might occur. The following sections show the most common issues and what can be done to solve them.

When linking your app, you might have an error in the following format:

Argument of type <type>| undefined' is not assignable to a parameter of type '<type>'.

This means that the argument is being declared as a certain type and is recognized as undefined.

Solution: You must ensure the argument is not undefined, or update the field type to be optional.

Errors may occur in the following scenario:

1. There is a lint configuration at the root of the project. It should be in files such as .eslintrc and .eslintignore.
2. The package.json file in the root is configured with an old version of TypeScript. For instance, the file has TypeScript version 3.9.6, but the Node builder 7.x uses 5.5.3.
3. Something (a class, a library, etc.) used in the code does not exist in the old TypeScript version.

Solution: Update the TypeScript version in the root package.json. We recommend using version 5.5.3, since it is used in the Node builder 7.x.

Side effect: If the app uses the eslint-config-vtex package, you will get a warning in the console about version incompatibility.

When linking your app, you might have errors like in the following examples:

• @vtex/tsconfig@0.6.0" has incorrect peer dependency "typescript@^
• eslint-config-vtex@10.1.0" has incorrect peer dependency "typescript@^3.3.3333"

These alerts may appear because some of the app's dependencies may run with an old TypeScript version.

ℹ️ Errors in this scenario might be due to some VTEX libraries not being updated yet with TypeScript 5.x. They should be updated gradually over time.

Solution: Update the package.json files of the dependencies manually with the new TypeScript version. We recommend using version 5.5.3, since it is the same used in the Node builder 7.x.

If you are accessing gobal.metrics in your code, defined by the node-vtex-api library, you should get the error:

Property 'metrics' does not exist on type 'typeof globalThis'.

This happens because of a breaking change between versions 12.x and 20.x of @types/node.

Solution: Use global as any, replacing global with (global as any) in your code. Example: (global as any).metrics.