In VTEX IO Services, Node Clients are powerful tools that enable you to seamlessly interact with both internal and external services. These clients play a crucial role in tasks such as making API requests, fetching data, and performing various operations within your VTEX IO apps. This guide will walk you through the effective utilization of Node Clients.

For this guide, note that VTEX IO Services exports functions that receive a context object. These functions can be resolver functions for GraphQL fields, middlewares for an HTTP server, or event handlers. In all cases, the Service receives a ctx object of type Context, and it is within ctx.clients where you will find your Clients.

Before diving into using Clients within your VTEX IO app, ensure you have the following prerequisites in place:

• VTEX IO development workspace: Ensure you have a VTEX IO development workspace set up. For more information, refer to Creating a Development workspace.
• TypeScript Familiarity: This guide assumes you have a basic understanding of TypeScript, as we'll be using the node Builder to develop with TypeScript. For more information, refer to Typescript's official documentation.
• Understanding of Clients: Clients play a crucial role in facilitating interactions between your application and both external and internal services. For more information, refer to Clients.

1. Start a new VTEX IO app using the node builder and open the project using your preferred code editor.

2. Open the terminal and change to your app's node folder.

3. Install the @vtex/api package by running the following command:

   
   

   _10

   yarn add @vtex/api

   
   

4. In your app's handlers and middlewares, access the desired Clients via the ctx object. Here's an example of accessing the @vtex/api native licenseManager Client:

   
   

   _10

   export const authorize = async (ctx: Context) {

   _10

   const { clients: { licenseManager } } = ctx

   _10

   ...

   _10

   const data = await licenseManager.canAccessResource(/*...*/)

   _10

   }

   
   

The @vtex/clients package exports Clients, Client Factories and TypeScript typings that help you connect a VTEX IO app with VTEX Core Commerce modules.

1. Start a new VTEX IO app using the node builder and open the project using your preferred code editor.

2. Open the terminal and change to your app's node folder.

3. Install the @vtex/api package by running the following command:

   
   

   _10

   yarn add @vtex/api

   
   

4. Install the @vtex/clients package by running the following command:

   
   

   _10

   yarn add @vtex/clients

   
   

5. Check the list of VTEX IO Clients available in the @vtex/clients package. Refer to List of native Clients and choose whether to use a Factory or an individual Client based on your requirements.

If you have developed custom Clients for a specific need, take the following steps to use them in your VTEX IO app.

For a practical example, you can refer to how the StatusClient is set up in the service-example.

1. After completing the steps in the Developing custom Clients guide, import the Clients class to the node/index.ts file.

   
   

   _10

   import { Clients } from "./clients";

   
   

2. Create or edit the clients object of type ClientsConfig<Clients> from @vtex/api. This code sets up the configuration for Clients available in ctx.clients. It specifies an implementation property as Clients, which points to the custom Clients imported in the previous step, providing access to your custom Clients and their functionality.

   
   

   _11

   import type { ClientsConfig } from "@vtex/api";

   _11

   _11

   const clients: ClientsConfig<Clients> = {

   _11

   implementation: Clients,

   _11

   options: {

   _11

   default: {

   _11

   retries: 2,

   _11

   timeout: 2000,

   _11

   },

   _11

   },

   _11

   };

   
   

   Note that inside the options property, there's a default key with default Client options. These options include specifying the number of retries and the timeout for HTTP requests. See the Options table for more options. All IO Clients will be initialized with these options unless otherwise specified.

3. (Optional) In the node/index.ts file, consider adding a type declaration to improve type safety and code clarity. This declaration helps you define the Context type, which is based on ServiceContext<Clients, State>.

   
   

   _10

   import type { ServiceContext } from "@vtex/api";

   _10

   _10

   declare global {

   _10

   type Context = ServiceContext<Clients, State>;

   _10

   }

   
   

4. In the node/index.ts file, export a new Service that defines route handlers and client options.

   
   

   _10

   export default new Service<Clients, State>({

   _10

   clients,

   _10

   routes: {

   _10

   ...

   _10

   },

   _10

   })

   
   

   For more information on how to set up routes, refer to the Routes guide.

5. Now, in your app's handlers and middlewares, use the clients object from the ctx to access your custom Client. Check the following example where we access the custom github Client in the authorize function.

   
   

   _10

   export const authorize = async (ctx: Context) {

   _10

   const { clients: { github } } = ctx

   _10

   ...

   _10

   const data = await github.getUser(/*...*/)

   _10

   }

   
   

The table below provides a detailed description of the available options for configuring your custom Client: