Skip to content
EvolveEvolveEvolve

config

@evolve-framework/config · v1.0.0

A service's configuration as a typed class. You declare each setting once, as a property with a type and a default, and load() fills it in from the places your platform keeps configuration: environment variables, a mounted secrets directory, a JSON or YAML file, or a cloud parameter store. Every value is checked and converted when the service starts, so a missing or malformed setting stops the service with a message naming the key and every place that was looked in.

When to use

  • You are writing an Evolve service and need its settings: every engine and CMS package ships a config class built on BaseConfig that yours extends.
  • Your settings live in more than one place, for example secrets in a mounted directory and the rest in the environment. Sources overlay in order, and the first one holding a key wins.
  • You want a cloud store as a source: the cloud-adapter-* packages build their parameter and secret stores on createIndexedSource from here.

Get started

  1. Install the package. It comes from the Evolve registry, which needs a one-time sign-in.

    pnpm add @evolve-framework/config
    Requirements1
    @types/node>=22optional

For example:

import { BaseConfig, envfield, envSource, fileSource } from "@evolve-framework/config";


class Config extends BaseConfig {
  readonly HTTP_PORT: number = 8080;


  readonly REDIS_URL: string;


  readonly API_SECRET: string;


  override config() {
    return {
      ...super.config(),
      HTTP_PORT: envfield.number(),
      REDIS_URL: envfield.string({ optional: true }),
      API_SECRET: envfield.secret(),
    };
  }
}


// Secrets mounted under /run/secrets win over the environment.
export const config = await Config.load({
  sources: [fileSource({ path: "/run/secrets" }), envSource()],
});

Entry points

@evolve-framework/configBaseConfig, the envfield field types, the sources (envSource, fileSource, documentSource), createIndexedSource for writing a source of your own, and the key transformers that match a store's key spelling to a property name26 exports
@evolve-framework/config/testingmemorySource, a plain record as a source, for testing a config class without the environment or a cloud1 export