vtex-io-service-runtime — Claude Code skill for VTEX IO runtime

What vtex-io-service-runtime does

Reach for this skill when the question is how a backend app runs inside the node builder. It treats node/index.ts as the composition root: route, event, and GraphQL handler registration belongs there, business logic does not. Large handler bodies, outbound API calls, or data mapping in that file are a signal to split things out before the service grows further.

Execution knobs sit in service.json rather than in handler code — timeout, memory, workers, minReplicas, maxReplicas, ttl, and rateLimitPerReplica. Routes stay private unless you set public: true on them. smartcache: true is meant for idempotent routes only; put it on an authenticated or write endpoint and repeated requests can get a response that was never theirs. Note that ttl counts minutes and is not a per-request timeout.

Context, State, and param types are shaped so middlewares and handlers share one contract, which keeps ctx.state, ctx.vtex, and params out of any. Authorization fields such as routes.access and routes.policies fall to auth-focused skills, and GraphQL schema or resolver design stays separate — this skill only wires handlers into the runtime.