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. However, this also means these apps need to be adjusted for the latest features.

Check the demo video below showing how to migrate your app to Node builder 7.x.

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, you can find 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, check if the typescript package is declared. If it is 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 don’t 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. Check 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 occur. 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 update is not exclusively fixing issues as in a patch, and a major version would require additional work.

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

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

If you need help migrating your app to 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 get 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’s 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 Node builder 7.x uses 5.5.3.
3. Something used in the code (a class, a library, etc.) doesn’t 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’s used in 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 get errors like 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 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’s the same used in Node builder 7.x.

If you’re accessing global.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.