VTEX IO: complete guide for e-commerce developers
VTEX IO is VTEX's development runtime that allows building custom applications using TypeScript, React and GraphQL. Unlike legacy CMS, IO offers a modern ecosystem with specialized builders, atomic deploys and workspace isolation. If you work with VTEX, understanding IO deeply is mandatory.
Builders: each with its role
IO organizes code into builders. The react builder renders storefront components. Node creates backends with Express-like middleware. GraphQL exposes schemas and resolvers. Messages handles internationalization. Store assembles Store Framework blocks. Each builder has its directory, config and build cycle. Mixing responsibilities between builders is the most common beginner mistake.
Custom Apps: when standard isn't enough
Custom apps solve what the standard ecosystem doesn't cover: specific business rules, internal system integrations, checkout extensions and automations. A VTEX IO app is a package with manifest.json, declared access policies and deploy via vtex publish. The key is keeping apps small and focused. An app that does everything becomes a monolith within the monolith.
Development workflow
IO development follows a cycle: vtex link for local development with hot reload, vtex deploy to publish to the test workspace, vtex install to install in the production workspace. Workspaces allow testing changes without affecting the live store. Native A/B testing compares workspaces with real traffic. Always test in a staging workspace before promoting to master.
Performance in VTEX IO
Poorly written apps are the main cause of slowness in VTEX stores. Avoid waterfall requests, use GraphQL cache with maxAge and stale, minimize JavaScript sent to the client and prefer server-side rendering whenever possible. Lighthouse is your best friend. Run it before and after every deploy.
When not to use custom apps
If the problem can be solved with admin configuration, a marketplace app or a theme adjustment, don't create a custom app. Each app adds complexity to build, deploy and maintenance. Evaluate the cost-benefit before opening the code editor.