vtex-io-service-configuration-apps

What this skill does

# Service Configuration Apps

## When this skill applies

Use this skill when a VTEX IO service should receive structured configuration from another app through the `configuration` builder instead of relying only on local app settings.

- Creating a configuration app with the `configuration` builder
- Exposing configuration entrypoints from a service app
- Sharing one configuration contract across multiple services or apps
- Separating configuration lifecycle from runtime app lifecycle
- Reading injected configuration through `ctx.vtex.settings`

Do not use this skill for:
- simple app-local configuration managed only through `settingsSchema`
- Store Framework block settings through `contentSchemas.json`
- generic service runtime wiring unrelated to configuration
- policy design beyond the configuration-specific permissions required

## Decision rules

- Treat the service app and the configuration app as separate responsibilities.
- The service app owns runtime (`node`, `graphql`, etc.), declares the `configuration` builder in `manifest.json`, defines `configuration/schema.json`, and reads injected values through `ctx.vtex.settings`.
- The configuration app does not own the service runtime. It should not declare `node` or `graphql` builders and usually has only the `configuration` builder.
- The configuration app points to the target service in the `configuration` field and provides concrete values in `<service-app>/configuration.json`.
- Use a configuration app when the configuration contract should live independently from the app that consumes it.
- Prefer a configuration app when multiple apps or services need to share the same configuration model.
- In service apps, expose configuration entrypoints explicitly through `settingsType: "workspace"` in `node/service.json` routes or events, or through `@settings` in GraphQL when the service should receive configuration from a configuration app.
- In configuration apps, the folder name under `configuration/` and the key in the `configuration` field should match the target service app ID, for example `shipping-service` in `vendor.shipping-service`.
- The shape of `configuration.json` must respect the JSON Schema declared by the service app.
- Read received configuration from `ctx.vtex.settings` inside the service runtime instead of making your own HTTP call just to fetch those values.
- Handlers and resolvers should cast or validate `ctx.vtex.settings` to match the configuration schema and apply defaults consistent with that schema.
- Treat configuration apps as a way to inject structured runtime configuration through VTEX IO context, not as a replacement for arbitrary operational data storage.
- Use `settingsSchema` when configuration is local to one app and should be edited directly in Apps > App Settings. Use configuration apps when the contract should be shared, versioned, or decoupled from the consuming app lifecycle.
- If a service configured through a configuration app fails to resolve workspace app configuration due to permissions, explicitly evaluate whether the manifest needs the `read-workspace-apps` policy for that scenario. Do not add this policy by default to unrelated services.
- For service configuration contracts, prefer closed schemas with `additionalProperties: false` and use `definitions` plus `$ref` when the structure becomes more complex.

## Hard constraints

### Constraint: Service apps must explicitly opt in to receiving configuration

A service app MUST declare where configuration can be injected, using `settingsType: "workspace"` in `node/service.json` routes or events, or the `@settings` directive in GraphQL.

**Why this matters**

Configuration apps do not magically apply to all service entrypoints. The service must explicitly mark which routes, events, or queries resolve runtime configuration.

**Detection**

If a service is expected to receive configuration but its routes, events, or GraphQL queries do not declare `settingsType` or `@settings`, STOP and expose the configuration boundary first.

**Correct**

```json
{
  "routes": {
    "status": {
      "path": "/_v/status/:code",
      "public": true,
      "settingsType": "workspace"
    }
  }
}
```

**Wrong**

```json
{
  "routes": {
    "status": {
      "path": "/_v/status/:code",
      "public": true
    }
  }
}
```

### Constraint: Configuration shape must be defined with explicit schema files

Configuration apps and the services they configure MUST use explicit schema files instead of implicit or undocumented payloads.

**Why this matters**

Without `configuration/schema.json` and matching `configuration.json` contracts, shared configuration becomes ambiguous and error-prone across apps.

**Detection**

If a configuration app is introduced without a clear schema file or the service accepts loosely defined configuration payloads, STOP and define the schema first.

**Correct**

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$ref": "#/definitions/ServiceConfiguration",
  "definitions": {
    "ServiceConfiguration": {
      "type": "object",
      "properties": {
        "bank": {
          "type": "object",
          "properties": {
            "account": { "type": "string" },
            "workspace": { "type": "string", "default": "master" },
            "version": { "type": "string" },
            "kycVersion": { "type": "string" },
            "payoutVersion": { "type": "string" },
            "host": { "type": "string" }
          },
          "required": ["account", "version", "kycVersion", "payoutVersion", "host"],
          "additionalProperties": false
        }
      },
      "required": ["bank"],
      "additionalProperties": false
    }
  }
}
```

**Wrong**

```json
{
  "anything": true
}
```

### Constraint: Consuming apps must read injected configuration from runtime context, not by inventing extra fetches

When a service is configured through a configuration app, it MUST consume the injected values from `ctx.vtex.settings` instead of creating its own ad hoc HTTP call just to retrieve the same configuration.

**Why this matters**

The purpose of configuration apps is to let VTEX IO inject the structured configuration directly into service context. Adding a custom fetch layer on top creates unnecessary complexity and loses the main runtime advantage of the builder.

**Detection**

If a service already exposes `settingsType` or `@settings` but still performs its own backend fetch to retrieve the same configuration, STOP and move the read to `ctx.vtex.settings`.

**Correct**

```typescript
export async function handleStatus(ctx: Context) {
  const settings = ctx.vtex.settings
  const code = ctx.vtex.route.params.code

  const status = resolveStatus(code, settings)
  ctx.body = { status }
}
```

**Wrong**

```typescript
export async function handleStatus(ctx: Context) {
  const settings = await ctx.clients.partnerApi.getSettings()
  ctx.body = settings
}
```

## Preferred pattern

Model the service and the configuration app as separate contracts:

1. The service app exposes where configuration can be resolved.
2. The service app defines accepted structure in `configuration/schema.json`.
3. The configuration app declares the service as a builder and supplies values in `configuration.json`.
4. The service reads the injected configuration through `ctx.vtex.settings`.

Example: service app `vendor.shipping-service`

`manifest.json`:

```json
{
  "vendor": "vendor",
  "name": "shipping-service",
  "version": "1.0.0",
  "builders": {
    "node": "7.x",
    "configuration": "1.x"
  }
}
```

`configuration/schema.json`:

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$ref": "#/definitions/ShippingConfiguration",
  "definitions": {
    "ShippingConfiguration": {
      "type": "object",
      "properties": {
        "carrierApi": {
          "type": "object",
          "properties": {
            "baseUrl": { "type": "string" },
            "apiKey": { "type": "string", "for