vtex-io-client-integration

You standardize VTEX IO client integrations by implementing Node clients with @vtex/api and @vtex/clients, registering them in an IOClients class, and consuming them via ctx.clients to ensure consistent auth, retries, and observability across all service calls.

The correct way to register and consume VTEX IO clients is to define a Clients class extending IOClients, register your client implementations there, and access them through ctx.clients inside middlewares and resolvers rather than instantiating them directly in handlers.

Use JanusClient in VTEX IO when calling Core Commerce APIs via Janus, and use ExternalClient for non-VTEX external APIs. Selecting the narrowest appropriate client abstraction ensures correct routing and authentication for each service boundary.

No, you cannot use raw HTTP libraries in VTEX IO apps. The architecture enforces constraints that forbid raw HTTP libraries and require client registry usage to maintain consistent transport, authentication, retries, and observability at the client boundary.

Configure retries and timeouts for VTEX IO Node clients by adjusting shared and per-client InstanceOptions. These options also let you tune headers, caching, and request metrics directly at the client boundary for reliable service-to-service HTTP calls.

You should normalize errors from external API calls near the client boundary in VTEX IO. Surface meaningful failures close to the client layer without hiding critical HTTP or transport details from middlewares and resolvers.