config-default
bsb/config-defaultDefault configuration plugin for profile and plugin resolution
config-default
config-default is the built-in configuration plugin for BSB.
It loads your deployment profile from YAML, resolves enabled plugins, and exposes typed plugin config at runtime.
What It Does
- Reads
sec-config.yaml(orBSB_CONFIG_FILE) - Selects active profile using
BSB_PROFILE(default:default) - Resolves plugin definitions for:
serviceseventsobservable
- Returns each plugin's
configobject to that plugin at startup
Bootstrap Source Of Truth
config-default bootstraps from environment variables first.
It cannot rely on sec-config.yaml to configure itself, because it is the component responsible for loading that file.
Use:
BSB_PROFILEBSB_CONFIG_FILEBSB_CONFIG_PLUGIN(when overriding)BSB_CONFIG_PLUGIN_PACKAGE(when overriding)
Typical sec-config.yaml Shape
default:
observable:
observable-default:
plugin: observable-default
enabled: true
config: {}
events:
events-default:
plugin: events-default
enabled: true
services:
service-my-api:
plugin: service-my-api
package: "@org/my-api"
enabled: true
config:
port: 3200
Note:
- You may include a
config.config-defaultblock for explicit metadata if desired. - It is not the bootstrap source for
BSB_PROFILE/BSB_CONFIG_FILE.
Environment Variables
BSB_PROFILE: active profile key in YAML (for exampledefault,production)BSB_CONFIG_FILE: path to YAML file (default./sec-config.yaml)BSB_CONFIG_PLUGIN: optional override plugin nameBSB_CONFIG_PLUGIN_PACKAGE: optional override package for config plugin
Environment Values Inside YAML
config-default does not perform ${VAR} or ${VAR:-default} interpolation inside sec-config.yaml.
If you need environment-driven values in plugin config, use one of:
- A custom config plugin that resolves env placeholders before returning config
- Explicit static values in YAML
When To Replace
Replace config-default if you need:
- Dynamic remote configuration
- Live config reload without process restart
- External secret backends
Config-Default Reference
This page covers the exact fields config-default reads and returns.
Top-Level Profile Structure
<profile-name>:
config: {}
observable: {}
events: {}
services: {}
Plugin Definition Fields
Each plugin entry supports:
plugin: plugin id, e.g.service-my-apipackage: npm package if external, e.g.@org/my-apienabled:true|falseversion: optional selector (major.minorormajor.minor.micro)config: plugin-specific payload passed to plugin config validation
Resolution Rules
- Service name in config is the mapped runtime name.
pluginis the implementation id loaded from package/lib.- If
enabled: false, plugin definition can still be read but is not started. - Missing profile key causes startup failure.
BSB_PROFILEandBSB_CONFIG_FILEare environment bootstrap values, not read from the YAML itself.
Example With Versioned External Package
default:
services:
service-registry:
plugin: service-bsb-registry
package: "@bsb/registry"
version: "1.0"
enabled: true
config:
database:
type: file
path: /mnt/temp/registry-data
Installation
npm i @bsb/baseConfiguration
Configuration for config plugins is provided through environment variables:
No configuration required