Configuration
This section covers AWS CDK Blocks for application settings and secrets.
AppSetting
A single configuration value that is not sensitive, such as a feature flag, an API URL, or a threshold. Read and update values at runtime. Values are typed and can be read in your API handlers without environment variable boilerplate.
Feature flags and runtime config for the whole app go in AppSetting. KVStore is for data your app writes. Production secrets, such as API keys, go in Secret.
Locally, AppSetting persists values to the filesystem in the .bb-data/ directory. On AWS, it provisions an SSM Parameter Store parameter. Best for feature flags and any configuration that might change without a redeploy.
You can mark a setting as secret: true to store it as an SSM SecureString. This is a fallback for a secret of little value in a prototype, not for production secrets. A secret: true setting cannot take a value in code. CDK Blocks seeds it with a random string on first deploy, and you set the real value later.
For more information, see bb-app-setting on GitHub
Secret
A single secret stored in AWS Secrets Manager. Use Secret for production credentials such as third-party API keys, OAuth client secrets, connection strings, and signing keys. This includes the client secret of an Auth provider. Each Secret is one Secrets Manager secret. The declaration holds only the name, never the value.
// Read-only (the default). Set the value after deploy. const paymentsKey = new Secret(scope, 'payments-api-key'); // Random value created on first deploy, for keys nobody needs to read. const signingKey = new Secret(scope, 'session-signing-key', { generate: true }); // The app writes this value itself, so it opts in to put(). const partnerToken = new Secret(scope, 'partner-token', { allowRuntimeWrite: true }); // A secret created and managed outside this app. const sharedKey = new Secret(scope, 'shared-key', { secret: Secret.fromExisting('arn:aws:secretsmanager:us-east-1:111122223333:secret:shared-key-AbCdEf'), }); export const billing = new ApiNamespace(scope, 'billing', () => ({ async charge(amount: number) { const key = await paymentsKey.get(); if (key === null) throw new ApiError('Payments are not configured', 503); // Call the payment API with key and amount. }, }));
get() returns null when no value is set. A new secret starts empty unless you pass generate: true. Don’t combine generate with schema, because a random string is not valid JSON.
Runtime access
A Secret is read-only at runtime by default. The object has only get() and listVersions(), and the app’s execution role can only read the secret. Pass allowRuntimeWrite: true to add put() and grant write access. This also applies to a secret wrapped with fromExisting().
Secret options
Secret also takes these options:
-
name: a fixed Secrets Manager name, so a script or CI pipeline can set the value with the AWS CLI. By default, CDK Blocks derives a name that is unique in your stack. -
schema: a schema from any Standard Schema library, such as Zod, for a typed JSON secret. Values are checked onget()andput(). -
cacheTtlSeconds: how long the runtime reuses a fetched value before it reads again. The default is 300 seconds, so a value rotated outside the app is picked up within 5 minutes without a redeploy. Set0to turn off caching. Aput()from the app clears the cache. -
secret: passSecret.fromExisting(arn)to use a secret that already exists, such as one shared by many apps. CDK Blocks does not create, seed, tag, or delete it. It only reads it, writes it if you allow, and grants access.
Secret versions
Each change keeps the old value as the previous version. Locally, only changes that you make with put() do. A hand edit of .bb-data/settings.json does not. Read it with get({ version: 'previous' }), for example to accept tokens signed with the old key during a rotation. listVersions() returns the current and previous versions (metadata only), and you can pass one back to get({ version }).
Setting a secret value
To set a value after deploy, open the /aws-blocks/settings route of your API. It redirects to your stack’s settings resource group in the AWS Resource Groups console, where Secret values appear next to AppSetting parameters. You can also give the secret a fixed name and set it with aws secretsmanager put-secret-value. Scaffolded apps include an npm run secret script, but it manages a separate set of secrets under the app’s blocks/<stackId>/secrets/ prefix. It does not set Secret values.
Secrets in local development
Locally, Secret stores the current value as plain text in .bb-data/settings.json, the same file AppSetting uses, and the previous value in .bb-data/secret-versions.json. The local /aws-blocks/settings route opens that file in your editor. generate: true seeds a random value locally too, and cacheTtlSeconds has no effect. Never use real credentials locally. Secret runs only on the server. aws-cdk-blocks does not export it to browser code, so browser code that imports it from there fails to build or to load. The browser build of @aws-cdk-blocks/bb-secret throws SecretErrors.NotSupported when you construct a Secret.
For more information, see bb-secret package source