| name | vtex-io-app-contract |
| description | Apply when defining or changing the contract of a VTEX IO app through manifest.json, builder declarations, dependencies, peerDependencies, billingOptions, and app identity. Covers how the app declares capabilities and integration boundaries. Use for scaffolding apps, splitting responsibilities across apps, or fixing contract-level link and publish issues.
|
| metadata | {"track":"vtex-io","tags":["vtex-io","manifest","app-contract","builders","dependencies","peer-dependencies","billing-options"],"globs":["manifest.json","package.json","node/package.json"],"version":"1.0","purpose":"Decide what a VTEX IO app exposes as contract and which capabilities belong in its manifest","applies_to":["scaffolding new VTEX IO apps","defining builders for app capabilities","choosing dependencies vs peerDependencies","defining billing behavior at the app contract level","fixing manifest-level link and publish failures","splitting responsibilities across multiple IO apps"],"excludes":["service runtime behavior and service.json tuning","HTTP route design and middleware chains","GraphQL schema and resolver implementation","frontend rendering and block composition","policy and auth enforcement details"],"decision_scope":["which capabilities belong in this app contract","which builders the manifest should declare","when to use dependencies vs peerDependencies","when to keep or split responsibilities across apps","how app contracts compose safely across edition apps and host environments"],"vtex_docs_verified":"2026-04-24"} |
App Contract & Builder Boundaries
When this skill applies
Use this skill when the main decision is about what a VTEX IO app is, what capabilities it declares, and which integration boundaries it publishes through manifest.json.
- Creating a new VTEX IO app and defining its initial contract
- Adding or removing builders to match app capabilities
- Choosing between
dependencies and peerDependencies
- Deciding whether a capability belongs in the current app or should move to another app
- Troubleshooting link or publish failures caused by manifest-level contract issues
Do not use this skill for:
- service runtime behavior such as
service.json, memory, workers, or route exposure
- HTTP handler implementation, middleware composition, or event processing
- GraphQL schema, resolver, or data-fetching implementation
- storefront, admin, or render-runtime frontend behavior
- policy modeling and security boundary enforcement
Decision rules
- Treat
manifest.json as the app contract. It declares identity, builders, dependencies, peer dependencies, and high-level capabilities that other apps or the platform rely on.
- Add a builder only when the app truly owns that capability. Builders are not placeholders for future work.
- Keep the contract narrow. If a manifest starts to represent unrelated concerns, split those concerns into separate apps instead of creating a catch-all app.
- Use
dependencies only for apps that can be safely auto-installed as part of the current app contract. Use peerDependencies for apps that must already exist in the environment, remain externally managed, or declare billingOptions.
- Keep naming and versioning publishable:
vendor, name, and version must form a stable identity that can be linked, published, and consumed safely.
- Keep
billingOptions aligned with the commercial contract of the app. If the app has billing implications, declare them explicitly in the manifest rather than leaving pricing behavior implicit.
- Apps that declare
billingOptions cannot be consumed through dependencies. If the current app requires a billable app, model that relationship with peerDependencies and require manual installation by the account or edition owner.
- Edition apps are compositions of app contracts, not exceptions to them. Keep each underlying app contract explicit, narrow, and semver-safe so composition stays predictable across host environments.
manifest.json can also declare app-level permissions and configuration surfaces, but detailed policy modeling belongs in security-focused skills and detailed settingsSchema design belongs in app-settings skills.
This is not an exhaustive list of builders; see the official Builders docs for the full catalog.
Builder ownership reference:
| Builder | Own this builder when the app contract includes |
|---|
node | backend runtime capability owned by this app |
graphql | GraphQL schema exposure owned by this app |
react | React bundles owned by this app |
admin | Admin UI surfaces owned by this app |
store | Store Framework block registration owned by this app |
messages | localized message bundles owned by this app |
pixel | storefront pixel injection owned by this app |
masterdata | Master Data schema assets owned by this app |
Contract boundary heuristic:
- If the capability is shipped, versioned, and maintained with this app, declare its builder here.
- If the capability is only consumed from another app, declare a dependency instead of duplicating the builder.
- If the capability introduces a separate runtime, security model, or release cadence, consider splitting it into another app.
Hard constraints
Constraint: Every shipped capability must be declared in the manifest contract
If the app ships a processable VTEX IO capability, manifest.json MUST declare the corresponding builder. Do not rely on folder presence alone, and do not assume VTEX IO infers capabilities from the repository structure.
Symmetrically, do not declare builders for capabilities that are not actually shipped by this app.
Why this matters
VTEX IO compiles and links apps based on declared builders, not on intent. If the builder is missing, the platform ignores that capability and the app contract becomes misleading. The app may link partially while the expected feature is absent.
Detection
If you see a maintained /node, /react, /graphql, /admin, /store, /messages, /pixel, or /masterdata directory, STOP and verify that the matching builder exists in manifest.json. If the builder exists but the capability does not, STOP and remove the builder or move the capability back into scope.
Correct
{
"vendor": "acme",
"name": "reviews-platform",
"version": "0.4.0",
"builders": {
"node": "7.x",
"graphql": "1.x",
"messages": "1.x"
}
}
Wrong
{
"vendor": "acme",
"name": "reviews-platform",
"version": "0.4.0",
"builders": {
"messages": "1.x"
}
}
The app ships backend and GraphQL capabilities but declares only messages, so the runtime contract is incomplete and the platform ignores the missing builders.
Constraint: App identity and versioning must stay publishable and semver-safe
The vendor, name, and version fields MUST identify a valid VTEX IO app contract. Use kebab-case for the app name, keep the vendor consistent with ownership, and use full semantic versioning.
Why this matters
Consumers, workspaces, and release flows rely on app identity stability. Invalid names or incomplete versions break linking and publishing, while identity drift creates unsafe upgrades and hard-to-debug dependency mismatches.
Detection
If you see uppercase characters, underscores, non-semver versions, or vendor/name changes mixed into unrelated work, STOP and validate whether the change is intentional and release-safe.
Correct
{
"vendor": "acme",
"name": "order-status-dashboard",
"version": "2.1.0"
}
Wrong
{
"vendor": "AcmeTeam",
"name": "Order_Status_Dashboard",
"version": "2.1"
}
This identity is not safely publishable because the name is not kebab-case and the version is not valid semver.
Constraint: Major version bumps on content-holding apps invalidate stored content
If the app ships any of store/blocks.json, store/routes.json, store/templates/, or store/contentSchemas.json (i.e. it is a content-holding app in the Store Framework sense), the version field MUST be treated as merchant-facing. A vtex release major on this app changes the key prefix that vtex.pages-graphql uses to look up every Site Editor edit, every custom route, and every per-template render cache.
Why this matters
vtex.pages-graphql keys merchant content by vendor.app@MAJOR.x:template. A patch and a minor bump preserve the key. A major bump changes it. After the major bump, none of the previously authored content is visible to the resolver under the active major key, and the storefront falls back to default vtex.store-theme content. The official recovery path is the updateThemeIds mutation in vtex.pages-graphql@2.x, executed in a production-flag dev workspace after installing the new major and before promoting; it rekeys all Site Editor edits, Pages, and Redirects from the old major to the new one.
Detection
Before approving vtex release major on an app whose manifest declares "store" in builders (or that ships any file under store/), STOP and require an explicit updateThemeIds migration plan in a production-flag dev workspace. The same rule applies before installing any new MAJOR of such an app on a production account.
Correct
vtex release patch
vtex release minor
Wrong
vtex release major
vtex publish
vtex install acme.store-theme@5.0.0
See vtex-io-storefront-theme-versioning for the safe install, updateThemeIds migration, smoke-test, promote, and rollback flow for content-holding apps.
Constraint: Dependencies and peerDependencies must express installation intent correctly
Use dependencies only for apps that this app should install as part of its contract and that can be auto-installed safely. Use peerDependencies for apps that must already be present in the environment, should remain externally managed, or declare billingOptions.
Why this matters
This is the core contract boundary between your app and the rest of the VTEX IO workspace. Misclassifying a relationship causes broken installations, hidden coupling, and environment-specific behavior that only appears after link or publish. In particular, builder-hub rejects dependencies on apps that declare billingOptions.
Detection
If the app requires another app to function in every environment, STOP and confirm whether it belongs in dependencies or peerDependencies. If the target app declares billingOptions, STOP and move it to peerDependencies. If the app only integrates with a platform capability, host app, edition-managed app, or paid app that the account is expected to manage manually, STOP and keep it out of dependencies.
Correct
{
"dependencies": {
"vtex.search-graphql": "0.x"
},
"peerDependencies": {
"vtex.store": "2.x",
"vtex.paid-app-example": "1.x"
}
}
Wrong
{
"dependencies": {
"vtex.store": "2.x",
"vtex.paid-app-example": "1.x"
},
"peerDependencies": {}
}
This contract hard-installs a host app that should usually be externally managed and also attempts to auto-install a billable app, which builder-hub rejects.
Preferred pattern
Start by deciding the smallest useful contract for the app, then declare only the identity and builders required for that contract.
Recommended manifest for a focused service-plus-GraphQL app:
{
"vendor": "acme",
"name": "reviews-platform",
"version": "0.1.0",
"title": "Reviews Platform",
"description": "VTEX IO app that owns review APIs and review GraphQL exposure",
"builders": {
"node": "7.x",
"graphql": "1.x",
"messages": "1.x"
},
"billingOptions": {
"type": "free"
},
"dependencies": {
"vtex.search-graphql": "0.x"
},
"peerDependencies": {
"vtex.store": "2.x"
}
}
Recommended contract split:
reviews-platform/
├── manifest.json # identity, builders, dependencies, peerDependencies
├── node/ # backend capability owned by this app
├── graphql/ # GraphQL capability owned by this app
└── messages/ # app-owned translations
reviews-storefront/
├── manifest.json # separate release surface for storefront concerns
├── react/
└── store/
Use this split when the backend/API contract and the storefront contract have different ownership, release cadence, or integration boundaries.
Common failure modes
- Declaring builders for aspirational capabilities that the app does not yet own, which makes the contract broader than the real implementation.
- Using one large manifest to represent backend runtime, frontend rendering, settings, policies, and integration concerns that should be separated into multiple skills or apps.
- Putting host-level apps in
dependencies when they should remain peerDependencies.
- Pinning exact dependency versions instead of major-version ranges such as
0.x, 1.x, or 3.x.
- Treating
manifest.json as a dumping ground for runtime or security details that belong in more specific skills.
- Modeling
settingsSchema here instead of using this skill only to decide whether app-level configuration belongs in the contract at all.
Review checklist
Related skills
Reference
