← Back to Browse
nodejs config CORE v9.0.3

config-default

config-default

Default configuration plugin for profile and plugin resolution

core config default

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 (or BSB_CONFIG_FILE)
  • Selects active profile using BSB_PROFILE (default: default)
  • Resolves plugin definitions for:
    • services
    • events
    • observable
  • Returns each plugin's config object 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_PROFILE
  • BSB_CONFIG_FILE
  • BSB_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-default block 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 example default, production)
  • BSB_CONFIG_FILE: path to YAML file (default ./sec-config.yaml)
  • BSB_CONFIG_PLUGIN: optional override plugin name
  • BSB_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-api
  • package: npm package if external, e.g. @org/my-api
  • enabled: true|false
  • version: optional selector (major.minor or major.minor.micro)
  • config: plugin-specific payload passed to plugin config validation

Resolution Rules

  • Service name in config is the mapped runtime name.
  • plugin is 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_PROFILE and BSB_CONFIG_FILE are 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

Install plugin (Node.js) 
npm i @bsb/base

Configuration

Configuration for config plugins is provided through environment variables:

BSB_PROFILE BSB_PROFILE string default: "default"
BSB_CONFIG_FILE BSB_CONFIG_FILE string default: "./sec-config.yaml"

Available Versions

v9.0.3

Metadata

Author BetterCorp (PTY) Ltd License (AGPL-3.0-only OR Commercial) Homepage https://bsbcode.dev/ Repository git+https://github.com/BetterCorp/better-service-base.git Published 2026-02-22T00:53:57.414Z Updated 2026-02-22T00:53:57.415Z Visibility public