vtex-io-http-routes
Apply when designing or implementing HTTP endpoints exposed by a VTEX IO backend service. Covers route boundaries, handler structure, middleware composition, request validation, and response modeling for service.json routes. Use for webhook endpoints, partner integrations, callback APIs, or reviewing VTEX IO handlers that should expose explicit HTTP contracts.
- Installs
- 1.2K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/vtex/skills --skill vtex-io-http-routes- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads vtex-io-http-routes automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
HTTP Routes & Handler Boundaries
When this skill applies
Use this skill when a VTEX IO service needs to expose explicit HTTP endpoints through service.json routes and implement the corresponding handlers under node/.
- Building callback or webhook endpoints
- Exposing integration endpoints for partners or backoffice flows
- Structuring route handlers and middleware chains
- Validating params, query strings, headers, or request bodies
- Standardizing response shape and status code behavior
Do not use this skill for:
- sizing or tuning the service runtime
- deciding app policies in
manifest.json - designing GraphQL APIs
- modeling async event or worker flows
Decision rules
- Use HTTP routes when the integration needs explicit URL contracts, webhooks, or callback-style request-response behavior.
- In VTEX IO,
service.jsondeclares route IDs, paths, and exposure such aspublic, while the Node entrypoint wires those route IDs to handlers exported fromnode/routes. Middlewares are composed in code, not declared directly inservice.json. - Keep route handlers small and explicit. Route code should validate input, call domain or integration services, and shape the response.
- Put cross-cutting concerns such as validation, request normalization, or shared auth checks into middlewares instead of duplicating them across handlers.
- Define route params, query expectations, and body shape as close as possible to the handler boundary.
- Use consistent status codes and response structures for similar route families.
- For webhook or callback endpoints, follow the caller's documented expectations for status codes and error bodies, and keep responses small and deterministic to avoid ambiguous retries.
- Emit structured logs or metrics for critical routes so failures, latency, and integration health can be diagnosed without changing the handler contract.
- Prefer explicit route files grouped by bounded domain such as
routes/orders.tsorroutes/catalog.ts. - Treat public routes as explicit external contracts. Do not expand a route to public use without reviewing validation, auth expectations, and response safety.
Hard constraints
Constraint: Route handlers must keep the HTTP contract explicit
Each route handler MUST make the request and response contract understandable at the handler boundary. Do not hide required params, body fields, or status code decisions deep inside unrelated services.
Why this matters
HTTP integrations depend on predictable contracts. When validation and response shaping are implicit or scattered, partner integrations become fragile and errors become harder to diagnose.
Detection
If the handler delegates immediately without validating required params, query values, headers, or request body shape, STOP and make the contract explicit before proceeding.
Correct
export async function getOrder(ctx: Context, next: () => Promise<void>) {
const { id } = ctx.vtex.route.params
if (!id) {
ctx.status = 400
ctx.body = { message: 'Missing route param: id' }
return
}
const order = await ctx.clients.partnerApi.getOrder(id)
ctx.status = 200
ctx.body = order
await next()
}
Wrong
export async function getOrder(ctx: Context) {
ctx.body = await handleOrder(ctx)
}
Constraint: Shared route concerns must live in middlewares, not repeated in every handler
Repeated concerns such as validation, request normalization, or common auth checks SHOULD be implemented as middlewares and composed through the route chain.
Why this matters
Duplicating the same checks in many handlers creates drift and inconsistent route behavior. Middleware keeps the HTTP surface easier to review and evolve.
Detection
If multiple handlers repeat the same body validation, header checks, or context preparation, STOP and extract a middleware before adding more duplication.
Correct
export async function validateSignature(ctx: Context, next: () => Promise<void>) {
const signature = ctx.request.header['x-signature']
if (!signature) {
ctx.status = 401
ctx.body = { message: 'Missing signature' }
return
}
await next()
}
Wrong
export async function routeA(ctx: Context) {
if (!ctx.request.header['x-signature']) {
ctx.status = 401
return
}
}
export async function routeB(ctx: Context) {
if (!ctx.request.header['x-signature']) {
ctx.status = 401
return
}
}
Constraint: HTTP routes should not absorb async or batch work that belongs in events or workers
Routes MUST keep request-response latency bounded. If a route triggers expensive, retry-prone, or batch-oriented work, move that work to an async flow and keep the route as a thin trigger or acknowledgment boundary.
Why this matters
Long-running HTTP handlers create poor integration behavior, timeout risk, and operational instability. VTEX IO services should separate immediate route contracts from background processing.
Detection
If a route performs large loops, batch imports, heavy retries, or work that is not required to complete before responding, STOP and redesign the flow around async processing.
Correct
export async function triggerImport(ctx: Context) {
await ctx.clients.importApi.enqueueImport(ctx.request.body)
ctx.status = 202
ctx.body = { accepted: true }
}
Wrong
export async function triggerImport(ctx: Context) {
for (const item of ctx.request.body.items) {
await ctx.clients.importApi.importItem(item)
}
ctx.status = 200
}
Preferred pattern
Recommended file layout:
node/
├── routes/
│ ├── index.ts
│ ├── orders.ts
│ └── webhooks.ts
└── middlewares/
├── validateBody.ts
└── validateSignature.ts
Wiring routes in VTEX IO services:
In VTEX IO, service.json declares route IDs and paths, the Node entrypoint registers a routes object in new Service(...), and node/routes/index.ts maps each route ID to the final handler. Middlewares are composed in code, not declared directly in service.json.
{
"routes": {
"orders-get": {
"path": "/_v/orders/:id",
"public": false
},
"reviews-create": {
"path": "/_v/reviews",
"public": false
}
}
}
// node/index.ts
import type { ClientsConfig, RecorderState, ServiceContext } from '@vtex/api'
import { Service } from '@vtex/api'
import { Clients } from './clients'
import routes from './routes'
const clients: ClientsConfig<Clients> = {
implementation: Clients,
options: {
default: {
retries: 2,
timeout: 800,
},
},
}
declare global {
type Context = ServiceContext<Clients, RecorderState>
}
export default new Service<Clients, RecorderState>({
clients,
routes,
})
Minimal route pattern:
// node/routes/index.ts
import type { RouteHandler } from '@vtex/api'
import { createReview } from './reviews'
import { getOrder } from './orders'
const routes: Record<string, RouteHandler> = {
'orders-get': getOrder,
'reviews-create': createReview,
}
export default routes
// node/routes/orders.ts
import { compose } from 'koa-compose'
import { validateSignature } from '../middlewares/validateSignature'
async function rawGetOrder(ctx: Context, next: () => Promise<void>) {
const { id } = ctx.vtex.route.params
if (!id) {
ctx.status = 400
ctx.body = { message: 'Missing route param: id' }
return
}
const order = await ctx.clients.partnerApi.getOrder(id)
ctx.status = 200
ctx.body = order
await next()
}
export const getOrder = compose([validateSignature, rawGetOrder])
export async function createReview(ctx: Context, next: () => Promise<void>) {
const body = ctx.request.body
if (!body?.productId) {
ctx.status = 400
ctx.body = { message: 'Missing productId' }
return
}
const review = await ctx.clients.reviewApi.createReview(body)
ctx.status = 201
ctx.body = review
await next()
}
Keep domain logic in services or integrations, and keep route handlers responsible for HTTP concerns such as validation, status codes, headers, and response shape.
Common failure modes
- Hiding request validation inside unrelated services instead of making route expectations explicit.
- Repeating the same auth or normalization logic in many handlers instead of using middleware.
- Letting HTTP handlers perform long-running async or batch work.
- Returning inconsistent status codes or response shapes for similar endpoints.
- Expanding a route to public exposure without reviewing its trust boundary.
Review checklist
- Is HTTP the right exposure mechanism for this contract?
- Are required params, headers, query values, and body fields validated at the route boundary?
- Are repeated concerns factored into middlewares?
- Does the handler stay small and focused on HTTP concerns?
- Should any part of the work move to async events or workers instead?
Related skills
vtex-io-events-and-workers- Use when expensive or retry-prone work should move out of HTTP handlers into async flowsvtex-io-auth-and-policies- Use when deciding which policies or access rules should protect HTTP routes
Reference
- Service - Route declaration and service exposure
- Node Builder - Backend file layout and route implementation context
- Using Node Clients - Client usage from route handlers
FAQ
What does the vtex-io-http-routes skill do?
Apply when designing or implementing HTTP endpoints exposed by a VTEX IO backend service. Covers route boundaries, handler structure, middleware composition, request validation, and response modeling for service.json routes. Use for webhook endpoints, partner integrations, callback APIs, or reviewing VTEX IO handlers that should expose explicit HTTP contracts.
How do I install vtex-io-http-routes?
Run npx skills add https://github.com/vtex/skills --skill vtex-io-http-routes in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/vtex-io-http-routes/ (personal) or .claude/skills/vtex-io-http-routes/ (project).
Which AI agents can use vtex-io-http-routes?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is vtex-io-http-routes safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains vtex-io-http-routes?
It is published by vtex in vtex/skills. It has 1,152 recorded installs.
More from vtex/skills
vtex-io-react-apps
vtex/skills
Apply when building React components under react/ or configuring store blocks in store/ for VTEX IO apps. Covers interfaces.json, contentSchemas.json for Site Editor, VTEX Styleguide for admin apps, and css-handles for storefront styling. Use for creating custom storefront components, admin panels, pixel apps, or any frontend development within the VTEX IO react builder ecosystem.
vtex-io-service-apps
vtex/skills
Apply when building backend service apps under node/ in a VTEX IO project or configuring service.json routes. Covers the Service class, middleware functions, ctx.clients pattern, JanusClient, ExternalClient, MasterDataClient, and IOClients registration. Use for implementing backend APIs, event handlers, or integrations that must use @vtex/api clients instead of raw HTTP libraries.
vtex-io-masterdata
vtex/skills
Apply when working with MasterData v2 entities, schemas, or MasterDataClient in VTEX IO apps, or when anyone designing or implementing a solution must scrutinize whether Master Data is the correct storage. The skill prompts hard questions: native Catalog or other VTEX stores, OMS, or an external database may be better; do not default to MD because it is convenient. Covers JSON Schema, CRUD, triggers, search and scroll, schema lifecycle, purchase-path avoidance, single source of truth, and BFF handoffs. Use for justified custom persistence while avoiding the 60-schema limit.
vtex-io-graphql-api
vtex/skills
Apply when working with GraphQL schema files in graphql/ or implementing resolvers in node/resolvers/ for VTEX IO apps. Covers schema.graphql definitions, @cacheControl and @auth directives, custom type definitions, and resolver registration in the Service class. Use for exposing data through GraphQL queries and mutations with proper cache control and authentication enforcement.
vtex-io-storefront-react
vtex/skills
Apply when building VTEX IO storefront components under react/ for Store Framework experiences. Covers storefront component structure, css-handles, storefront context hooks, browser-safe data fetching, and how components should behave when used as theme blocks. Use for custom storefront UI, product widgets, banners, forms, or reviewing shopper-facing React code in VTEX IO apps.
vtex-io-app-settings
vtex/skills
Apply when defining, validating, or consuming VTEX IO app settings. Covers settingsSchema, app-level configuration boundaries, and how backend or frontend code should depend on settings safely. Use for merchant-configurable behavior, settings forms, or reviewing whether settings belong in app configuration rather than hardcoded logic or custom data entities.
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.