AppSetting

A single application configuration value backed by SSM Parameter Store.

When to use: You need a non-sensitive configuration value (feature flag, API URL, threshold) stored as a single SSM parameter. Each AppSetting instance maps to exactly one parameter.

When NOT to use: For a production secret (API key, OAuth client secret, database connection string, token), use Secret — it is the recommended home for credentials that protect a production app, in line with AWS guidance. AppSetting with secret: true does encrypt the value at rest and is free, so it is a fine fallback for a low-value secret in a prototype — but it is not the recommended place for production secrets. If you need structured key-value data with conditional writes and queries, use KVStore or DistributedTable.

Design & mock parity details: DESIGN.md

API

const setting = new AppSetting(scope, id, options)

Options

Customer-managed KMS key (kmsKeyArn): Provide a CMK ARN to control the decrypt/grant scope of a secret (e.g. cross-account access or a dedicated key policy). The construct grants the shared handler kms:Decrypt (plus kms:Encrypt for secrets it writes) on that specific key ARN. Because AWS Blocks does not own a bring-your-own key, the key's own key policy must also allow the app's Lambda execution role to use it (or delegate to IAM via the account-root statement CDK adds to same-account keys). Adding or changing kmsKeyArn on an already-deployed secret re-encrypts its current value under the new key on the next deploy, so decryption keeps working.

Naming: When you omit name, the framework derives a unique SSM path from the construct scope tree (/${fullId}). This is the recommended approach — it prevents collisions across stacks automatically. If you provide an explicit name, you are responsible for ensuring it is unique across all stacks deployed to the same AWS account and region.

Error Handling

import { isBlocksError } from '@aws-blocks/core';
import { AppSettingErrors } from '@aws-blocks/bb-app-setting';

try {
  await setting.put(value);
} catch (e: unknown) {
  if (isBlocksError(e, AppSettingErrors.ValidationFailed)) {
    // schema validation failed or value exceeds 4 KB
  }
  throw e;
}

try {
  const value = await setting.get();
} catch (e: unknown) {
  if (isBlocksError(e, AppSettingErrors.ParameterNotFound)) {
    // the parameter is missing (e.g., deleted out-of-band) or a secret has an empty value
  }
  throw e;
}

get() can throw AppSettingErrors.ParameterNotFound when the parameter does not exist or a secret parameter has an empty value (in both the AWS and mock runtimes).

Examples

Plain String Setting

// Recommended: let the framework manage the SSM name (unique by default)
const apiUrl = new AppSetting(scope, 'apiUrl', {
  value: 'https://api.example.com',
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getApiUrl() {
    return { url: await apiUrl.get() };
  },
  async setApiUrl(url: string) {
    await apiUrl.put(url);
  },
}));

Typed Object with Schema

import { z } from 'zod';

const config = new AppSetting(scope, 'config', {
  value: { maxRetries: 3, timeout: 5000 },
  schema: z.object({ maxRetries: z.number(), timeout: z.number() }),
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async getConfig() {
    return await config.get(); // { maxRetries: number; timeout: number }
  },
  async updateConfig(cfg: { maxRetries: number; timeout: number }) {
    await config.put(cfg); // validated against schema
  },
}));

Secret

const stripeKey = new AppSetting(scope, 'stripeKey', {
  secret: true,
});

export const api = new ApiNamespace(scope, 'api', (context) => ({
  async charge(amount: number) {
    const key = await stripeKey.get(); // decrypted from SSM SecureString
    // use key...
  },
}));

Explicit Name (Cross-Service Reads)

Use an explicit name when the SSM parameter must be read by other services or follow a well-known path convention.

⚠️ You must ensure this name is unique across all stacks deployed to the same AWS account and region to avoid collisions.

const apiUrl = new AppSetting(scope, 'apiUrl', {
  name: '/my-app/production/api-url',
  value: 'https://api.example.com',
});

Validation Rules

These are enforced at CDK synth time and in local development (the mock rejects the same combinations at construction):

• secret + schema → error (secrets are plain strings)
• schema without value → error (parameter needs a valid initial value)
• secret with value → error (don't put secrets in source code)
• Non-secret without value → error (settings require an initial value)

Scaling & Cost (AWS)

• String parameters: Standard tier, free, 4 KB limit, 10,000 per account/region
• SecureString parameters: Standard tier, free, encrypted with aws/ssm KMS key
• Throughput: 40 TPS default for GetParameter (can be increased)
• Latency: Single-digit ms reads and writes

Local Development

Mock data persists to disk at .bb-data/settings/{fullId}/value.json across dev server restarts. Wipe with rm -rf .bb-data. Secrets generate a random value locally (no KMS encryption in mock mode).