Extensions

Config Source

Configuration rarely lives in one place: some in the environment, some in a file, the secrets in a vault. @stone-js/config-source loads and merges it from many providers, env, JSON/YAML files, AWS SSM, Secrets Manager, an HTTP endpoint, into the blueprint before the app boots, so every middleware and provider sees the resolved config. Opt into live reload to refresh it on each request.

#Install

terminalbash

npm i @stone-js/config-source
# only the drivers you use (optional, lazy):
npm i @aws-sdk/client-ssm @aws-sdk/client-secrets-manager @aws-sdk/client-kms js-yaml

#Load before boot

The principle

Configuration is Setup, the first dimension: it must exist before anything reads it. The blueprint is built once, ahead of every event; the config belongs there, resolved, not fetched lazily halfway through a request.

In Stone.js

A @Configuration()'s configure(blueprint) is awaited during initBlueprint, before the blueprint middleware run. Load your sources there and the whole app boots with the merged config in place.

app/AppConfig.tsts

import { Configuration } from '@stone-js/core'
import { loadConfigSources, envSource, fileSource, ssmSource, secretsSource, kmsDecryptor } from '@stone-js/config-source'

@Configuration()
export class AppConfig {
  async configure (blueprint) {
    await loadConfigSources(blueprint, [
      envSource({ prefix: 'APP_' }),
      fileSource({ path: './config.yaml', optional: true }),
      ssmSource({ path: '/my-app/' }),
      secretsSource({ secretId: 'my-app/prod' })
    ], { transform: kmsDecryptor() })   // decrypts any "kms:…" value
  }
}

Sources merge in order, later wins. The transform runs on every leaf value.

#Live config

Mark the configuration live and Stone reloads it on every incoming event, its native live-config mechanism, no restart. Loaded once by default.

app/LiveConfig.tsts

@Configuration({ live: true })
export class LiveConfig {
  async configure (blueprint) {
    await loadConfigSources(blueprint, [ssmSource({ path: '/my-app/' })])
  }
}

#Sources

source	Type	Description
envSource	`built-in`	Environment variables; an optional prefix is stripped from the keys.
fileSource	`built-in`	A local JSON or YAML file; tolerate a missing one with optional.
ssmSource	`@aws-sdk`	AWS SSM Parameter Store, nested by path (/app/db/url -> db.url).
secretsSource	`@aws-sdk`	AWS Secrets Manager; the JSON secret becomes the config object.
httpSource	`built-in`	Any URL: a GitHub raw file, a gist, a config server.
kmsDecryptor	`@aws-sdk`	A transform that decrypts kms:-prefixed values via AWS KMS.