back
loading skill details...
Apply when defining, validating, or consuming VTEX IO app settings. Covers settingsSchema, app-level configuration boundaries, and how backend or frontend code…
App Settings & Configuration Boundaries
When this skill applies
Use this skill when deciding or implementing how a VTEX IO app should expose configurable settings.
Defining settingsSchema
Adding merchant-configurable app behavior
Reviewing whether configuration belongs in app settings or custom data
Reading and validating settings in app code
Do not use this skill for:
runtime infrastructure settings in service.json
Master Data entity design
policy declaration details
route auth modeling
Decision rules
Use app settings for stable configuration that merchants or operators should be able to manage explicitly.
Use settingsSchema for app-level configuration managed through VTEX Admin, and use store/contentSchemas.json for Store Framework block configuration that varies by page or block instance.
If the value is global for the app or account, it usually belongs in settingsSchema. If it varies per page, block, or theme composition, it usually belongs in contentSchemas.json.
Do not use app settings as a substitute for high-volume operational data storage.
Use JSON Schema explicitly with properties, required, default, enum, format, and related constraints instead of a generic root type: object only.
Use settingsSchema.access: "public" only for non-sensitive values that are intentionally safe to expose to frontend code through publicSettingsForApp.
If access is omitted, do not assume frontend GraphQL consumers can read the settings. Public frontend access must be an explicit choice.
Use app settings for API keys, tokens, and secrets instead of hardcoding them in the codebase.
Never expose secrets from app settings directly in HTTP responses, GraphQL responses, HTML, or browser-side props.
Never expose secrets from app settings in logs either.
For sensitive fields such as API keys or passwords, keep them as type: "string" and consider marking them with format: "password". Some platform consumers, such as Apps GraphQL when using hidePasswords, may use this metadata to mask values in responses. Do not rely on this as the only security layer: secrets must still be treated as backend-only and never exposed in responses or logs.
UI-specific hints such as ui:widget: "password" may be supported by some renderers, but they are not part of the core JSON Schema guarantees. Do not assume the standard VTEX Admin App Settings UI will enforce them.
Read backend settings through ctx.clients.apps.getAppSettings(ctx.vtex.appId ?? process.env.VTEX_APP_ID) and centralize normalization or validation in a helper instead of spreading ad hoc access patterns through handlers.
When reading or saving this app's own settings at runtime, use the correct app identifier such as process.env.VTEX_APP_ID or ctx.vtex.appId and rely on the app token plus standard app-settings permissions. Do not declare extra License Manager policies in manifest.json or add workspace-wide policies such as read-workspace-apps or undocumented policies such as write-workspace-apps just to "fix" a 403.
Pixel apps that need configuration should also consume settings through ctx.clients.apps.getAppSettings(...) on the backend side of the pixel app. If a value must be available to injected JavaScript, expose only non-sensitive fields through access: "public" and publicSettingsForApp, keeping secrets strictly on the server side.
Make code resilient to missing or incomplete settings by validating or applying defaults at the consumption boundary.
Never assume settings are identical across accounts or workspaces. Each workspace may have different app configuration during development, rollout, or debugging.
Settings vs configuration builder:
Use settingsSchema when the configuration is specific to this app and the merchant is expected to edit it in Apps > App Settings.
Consider a separate app using the configuration builder when the configuration contract needs to be shared across multiple apps, managed separately from the runtime app lifecycle, or injected directly into service context through ctx.vtex.settings.
Prefer a configuration app when the main goal is structured service configuration delivered through VTEX IO runtime context, instead of settings fetched ad hoc by the app itself.
Hard constraints
Constraint: Configurable app behavior must have a schema
Merchant-configurable settings MUST be modeled through an explicit schema instead of ad hoc unvalidated objects.
Why this matters
Without a schema, configuration becomes ambiguous, harder to validate, and easier to break across environments.
Detection
If code depends on app-level configuration but no schema or validation contract exists, STOP and define it first.
Correct
{
"settingsSchema": {
"title": "My App Settings",
"type": "object",
"properties": {
"enableModeration": {
"title": "Enable moderation",
"type": "boolean",
"default": false,
"description": "If true, new content will require approval before going live."
},
"apiKey": {
"title": "External API key",
"type": "string",
"minLength": 1,
"description": "API key for the external moderation service.",
"format": "password"
},
"mode": {
"title": "Mode",
"type": "string",
"enum": ["sandbox", "production"],
"default": "sandbox"
}
},
"required": ["apiKey"]
}
}
Wrong
const settings = ctx.state.anything
Constraint: Sensitive settings must stay backend-only and must not be exposed to the frontend
Secrets stored in app settings such as API keys, tokens, or passwords MUST be treated as backend-only configuration.
Why this matters
App settings are a natural place for secrets, but exposing them in HTTP responses, GraphQL payloads, HTML, or frontend props turns configuration into a security leak.
Detection
If a route, resolver, or frontend-facing response returns raw settings or includes sensitive fields from settings, STOP and move the external call or secret usage fully to the backend boundary.
Correct
const { apiKey } = await ctx.clients.apps.getAppSettings(
ctx.vtex.appId ?? process.env.VTEX_APP_ID
)
const result = await externalClient.fetchData({ apiKey })
ctx.body = result
Wrong
const settings = await ctx.clients.apps.getAppSettings(
ctx.vtex.appId ?? process.env.VTEX_APP_ID
)
ctx.body = settings
Constraint: Public app settings access must never expose sensitive configuration
If settingsSchema.access is set to public, the exposed settings MUST contain only values that are safe to ship to frontend code through publicSettingsForApp.
Why this matters
access: "public" is a delivery choice, not a security control. Once settings are publicly exposed, storefront or frontend code can read them, so secrets and backend-only configuration must never be included there.
Detection
If a settings schema marks access as public and includes API keys, tokens, passwords, or any value intended only for backend integrations, STOP and keep those settings private.
Correct
{
"settingsSchema": {
"title": "Public Storefront Settings",
"type": "object",
"access": "public",
"properties": {
"bannerText": {
"title": "Banner text",
"type": "string"
}
}
}
}
Wrong
{
"settingsSchema": {
"title": "My App Settings",
"type": "object",
"access": "public",
"properties": {
"apiKey": {
"title": "External API key",
"type": "string",
"format": "password"
}
}
}
}
Constraint: Settings must not be used as operational data storage
App settings MUST represent configuration, not high-volume mutable records.
Why this matters
Settings are for configuration boundaries, not for transactional or large-scale operational data.
Detection
If a proposed setting stores records that behave like orders, reviews, logs, or queue items, STOP and move that concern to a more appropriate data mechanism.
Correct
{
"enableModeration": true
}
Wrong
{
"allReviews": []
}
Constraint: Code must validate or default settings at the consumption boundary
Settings-dependent code MUST tolerate missing or incomplete values safely.
Why this matters
Configuration can drift across workspaces and accounts. Code that assumes every setting is present becomes fragile.
Detection
If code reads settings and assumes required fields always exist with no validation or defaults, STOP and make the dependency explicit.
Correct
const rawSettings = await ctx.clients.apps.getAppSettings(
ctx.vtex.appId ?? process.env.VTEX_APP_ID
)
const settings = normalizeSettings(rawSettings)
const enabled = settings.enableModeration ?? false
Wrong
const enabled = settings.enableModeration.value
Preferred pattern
Use settings for stable, merchant-managed configuration, define them with explicit JSON Schema properties, and validate or normalize them where they are consumed.
For secrets, keep the read and the external call on the backend and return only the business result to the frontend.
Use frontend GraphQL access only for intentionally public settings, and keep backend-only settings behind getAppSettings(...).
Common failure modes
Using settings as operational storage.
Using only type: object without explicit properties and validation details.
Reading settings without defaults or validation.
Exposing raw settings or secrets to the frontend.
Marking settings as access: "public" when they contain backend-only or sensitive values.
Logging settings or secrets in plain text.
Hardcoding API keys or tokens instead of storing them in app settings.
Adding workspace-level policies such as read-workspace-apps or invalid policies such as write-workspace-apps as a generic workaround for app settings permission errors, instead of validating the correct appId and standard app-settings permissions.
Using settingsSchema when the requirement is really block-level Store Framework configuration.
Creating schemas that are too broad or vague.
Review checklist
Does this data really belong in app settings?
Does the settingsSchema declare explicit properties with clear types and required only where necessary?
Are sensitive fields represented safely, for example as string fields with format: "password", knowing that some consumers such as Apps GraphQL with hidePasswords may use that metadata to mask the output?
Does the consuming code validate or default missing values?
Are secrets kept backend-only and never exposed to the frontend?
If access: "public" is used, are all exposed settings intentionally safe for frontend consumption?
Is the settings surface small and intentional?
Reference
Manifest - App configuration contract
Creating an interface for your app settings - settingsSchema, access, frontend queries, and backend settings consumption
Configuring your app settings - Pixel app example for consuming app settings in VTEX IOdon't have the plugin yet? install it then click "run inline in claude" again.
extracted implicit decision logic into explicit if-else branches, documented all external connections (VTEX Admin UI, Apps GraphQL, publicSettingsForApp), added edge cases like auth expiry and settings drift across workspaces, and clarified secret handling constraints with testable detection patterns.
use this skill when deciding how a VTEX IO app should expose configurable settings to merchants or operators. covers settingsSchema definition, validation boundaries, secret handling, and how backend or frontend code should read and normalize settings at runtime. apply when modeling app-level configuration through VTEX Admin, determining whether configuration belongs in app settings vs store/contentSchemas.json, or handling API keys and tokens safely.
inputs required to run this skill:
external connections:
edge cases to handle:
decide whether data belongs in app settings
define explicit settingsSchema in manifest.json
mark public vs private access explicitly
read settings on the backend at the consumption boundary
normalize and validate settings with defaults
use settings only for external API calls or business logic, never expose raw to frontend
for frontend access to non-sensitive settings, use publicSettingsForApp GraphQL query
handle pixel apps that need configuration
decide between settingsSchema and configuration builder
if merchant-configurable behavior is required, must settings be stored in app settings?
if a setting contains a secret (API key, token, password), how should it be handled?
if frontend code needs a configuration value, must all settings be marked access: "public"?
if getAppSettings returns incomplete or missing settings, should code assume defaults or fail?
if a workspace has different app configuration than another workspace, should code handle it?
if a 403 error occurs when calling getAppSettings, should custom policies be added to manifest.json?
success looks like: