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 use this builder effectively. For more information, see 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
3.x	8.x	-	3.9.7	Deprecated
4.x	12.x	-	3.9.7	Deprecated
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

We strongly recommend upgrading your Node app to the latest Node builder before legacy Node builder versions are deprecated. After deprecation, apps using a legacy builder version will continue to work, but you won't be able to release or publish new major versions. Follow the instructions in the Node builder 7.x migration guide to upgrade your Node app.

When building Node apps, all external dependencies must be compatible with Node.js 16.x. This is the runtime version used for validation during the build process.

Even if your app uses Node builder 7.x (which runs on Node.js 20.x), you still need to ensure that your libraries also support Node.js 16.x. Otherwise, the build may fail.

Always make sure that your dependencies are compatible with Node.js 16.x, even if your development environment or builder version runs on a newer runtime.

An app that uses the node builder has a node folder on its root, which contains the following files and directories:

• TypeScript code files (.ts extension) containing the core logic of the app, organized within directories such as:
  • clients: Directory with Clients code files.
  • middlewares: Directory with middleware code files.
  • event: Directory with event handler code files.
• index.ts: Main TypeScript code file, where the execution begins. This file contains the service's main class.
• package.json: JSON file describing dependencies, script commands for building, and version details.
• service.json: Service configuration file used for defining 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, follow these steps:

1. 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.
2. Configure the service.json file: Edit the service.json configuration file. For more information, see Service configuration parameters.
3. Configure permissions: If you want to access external resources, add the required policies for each resource in the manifest.json, and the corresponding Clients in the code to access those resources.
4. Implement the app's logic: Add the necessary TypeScript files containing the app logic.
5. Test: Link the app to a development workspace for testing.

See Engineering guidelines for guidance on scalability, performance optimization, data privacy best practices, and versioning.

Consider the following scenarios when using the node builder:

• Backend service development: If you're building backend services using Node.js, the node builder streamlines development with native functions and clients for integrating with the VTEX ecosystem.
• Event-driven applications: For apps that rely heavily on an event-driven architecture, where actions trigger responses asynchronously, use the node builder to implement event handlers and listeners.
• Integration with external systems: When your app needs to integrate with external systems or APIs, such as payment gateways, databases, or third-party services, the node builder helps you create client modules for interacting with these systems.
• Custom middleware: If your app requires custom middleware for tasks like authentication, logging, or request processing, the node builder supports creating and integrating middleware components.

Below are some app examples that use the node builder:

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