The node builder is used to develop backend apps with TypeScript code executed by the Node.js runtime. This guide aims to provide a comprehensive understanding of how to utilize this builder effectively. For further insights, refer to Developing services on VTEX IO.

The Node builder versions are defined in the table below. Each builder version is compatible with a specific version of the Node.js engine, @types/node package (TypeScript definitions for Node), and TypeScript. You can select the desired builder version in your app’s manifest.json file.

Builder version	Node.js	@types/node	TypeScript	Status
4.x	12.x	-	3.9.7	Active until March 2025
6.x	16.x	12.0.0	3.9.7	Active until June 2025
7.x	20.x	20.0.0	5.5.3	Active

Apps using deprecated builder versions won't link or build. For details about updating the Node builder version, see our migration guide.

An app that uses the node builder has a node folder on its root, where are located the following files and directories:

• TypeScript code files (.ts extension) containing the core logic of the app, organized within various directories, such as:
  • clients: Directory with the code files of Clients.
  • middlewares: Directory with the code files of middlewares.
  • event: Directory with the code files of event functions.
• index.ts: Main TyepScript code file, where the execution begins. This file contains the main class of the service.
• package.json: JSON file describing the dependencies, script commands for building, and version details.
• services.json: Service configuration file used for defining the app parameters such as routes, events, time-to-live, etc. For more details, see Service configuration parameters.
• tsconfig.json: JSON file containing build configuration options.

To develop an app using the node builder, refer to the following steps:

• Start with a template: Download the service-example template or create a new project using the vtex init CLI command and choose the service-example option.
• Configure the service.json file: Edit the service.json configuration file. For more information, see Service configuration parameters.
• Configure permissions: If you want to access external resources, add the necessary policies to get permission for each resource in the manifest.json and the corresponding Clients in the code to access the resources.
• Implement the app's logic: Add the necessary TypeScript files containing the app logic.
• Testing: Link the app to a development workspace for testing.

Refer to Engineering guidelines for further information on scalability, performance optimization, data privacy best practices, and versioning.

Consider the following scenarios when using the node builder:

• Backend service development: If you are building backend services using Node.js, the node builder provides a streamlined development experience with native functions and clients for integrating with the VTEX ecosystem.
• Event-driven applications: For applications that rely heavily on event-driven architecture, where actions trigger responses asynchronously, the node builder allows developers to implement event handlers and listeners.
• Integration with external systems: When your application needs to integrate with external systems or APIs, such as payment gateways, databases, or third-party services, the node builder facilitates the development of client modules for interacting with these systems.
• Custom middleware: If your application requires custom middleware for tasks like authentication, logging, or request processing, the node builder supports the creation and integration of middleware components.

Here are some app examples that use the node builder:

• orders-feed-example
• external-seller-example
• adyen-platforms
• mega-menu