@memberjunction/config

Central configuration loading and merging utilities for the MemberJunction framework. This package provides a standardized way for MJ packages to define default configurations, discover user override files, and merge them together with a deterministic precedence order.

Overview

MemberJunction applications are configured through a layered system where each package defines its own defaults and users supply overrides through a shared mj.config.cjs file. This package provides the infrastructure that makes that layering work: config file discovery (via cosmiconfig), deep merge with customizable strategies, structure validation, and environment-variable parsing helpers.

flowchart TD
    A["Package Defaults<br/>(hardcoded in each package)"] --> D["mergeConfigs()"]
    B["mj.config.cjs<br/>(user overrides)"] --> D
    C["Environment Variables"] --> E["parseBooleanEnv()"]
    E --> F["Final Runtime Config"]
    D --> F

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style B fill:#2d8659,stroke:#1a5c3a,color:#fff
    style C fill:#b8762f,stroke:#8a5722,color:#fff
    style D fill:#7c5295,stroke:#563a6b,color:#fff
    style E fill:#7c5295,stroke:#563a6b,color:#fff
    style F fill:#2d6a9f,stroke:#1a4971,color:#fff

Installation

npm install @memberjunction/config

If you are working inside the MemberJunction monorepo, add the dependency to the consuming package's package.json and run npm install at the repository root.

Configuration File Discovery

When loadMJConfig() is called it uses cosmiconfig to walk up the directory tree looking for the first matching file in the following order:

| Priority | File / Location | Format | |----------|----------------|--------| | 1 | mj.config.cjs | CommonJS | | 2 | mj.config.js | ESM / CommonJS | | 3 | .mjrc | JSON / YAML | | 4 | .mjrc.js | ESM / CommonJS | | 5 | .mjrc.cjs | CommonJS | | 6 | "mj" key in package.json | JSON |

The recommended convention across MemberJunction is mj.config.cjs placed at the repository root.

Usage

Loading Configuration (Async)

The primary entry point. It discovers the user's config file, merges it with the package defaults, and returns the result along with metadata about what was loaded.

import { loadMJConfig } from '@memberjunction/config';

interface MyPackageConfig {
  port: number;
  debug: boolean;
  database: {
    host: string;
    pool: { max: number; min: number };
  };
}

const MY_DEFAULTS: MyPackageConfig = {
  port: 4000,
  debug: false,
  database: {
    host: 'localhost',
    pool: { max: 50, min: 5 }
  }
};

const result = await loadMJConfig<MyPackageConfig>({
  defaultConfig: MY_DEFAULTS,
  verbose: true            // logs discovery / merge details
});

console.log(result.config);          // merged configuration object
console.log(result.hasUserConfig);   // true if mj.config.cjs was found
console.log(result.configFilePath);  // path to the discovered file
console.log(result.overriddenKeys);  // top-level keys the user changed

Loading Configuration (Sync)

For cases where an async call is not possible (CommonJS bootstrap code, for example), loadMJConfigSync accepts an explicit file path instead of searching the directory tree.

import { loadMJConfigSync } from '@memberjunction/config';

const config = loadMJConfigSync<MyPackageConfig>(
  '/absolute/path/to/mj.config.cjs',
  { defaultConfig: MY_DEFAULTS }
);

Building a Multi-Package Configuration

buildMJConfig composes defaults from several MJ packages into a single configuration object before applying user overrides. This is typically called at application startup.

import { buildMJConfig } from '@memberjunction/config';

const config = buildMJConfig(
  {
    server:    serverDefaults,
    codegen:   codegenDefaults,
    mcpServer: mcpDefaults,
    a2aServer: a2aDefaults,
    queryGen:  queryGenDefaults
  },
  userOverrides   // optional -- from mj.config.cjs
);

flowchart LR
    S["Server<br/>Defaults"] --> B["buildMJConfig()"]
    C["CodeGen<br/>Defaults"] --> B
    M["MCP Server<br/>Defaults"] --> B
    A["A2A Server<br/>Defaults"] --> B
    Q["QueryGen<br/>Defaults"] --> B
    U["User<br/>Overrides"] --> B
    B --> R["Unified Config"]

    style S fill:#2d6a9f,stroke:#1a4971,color:#fff
    style C fill:#2d6a9f,stroke:#1a4971,color:#fff
    style M fill:#2d6a9f,stroke:#1a4971,color:#fff
    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style Q fill:#2d6a9f,stroke:#1a4971,color:#fff
    style U fill:#2d8659,stroke:#1a5c3a,color:#fff
    style B fill:#7c5295,stroke:#563a6b,color:#fff
    style R fill:#b8762f,stroke:#8a5722,color:#fff

Merging Configurations Directly

mergeConfigs performs a deep merge of two plain objects. It is used internally by the loader functions and is also exported for packages that need to merge configuration fragments on their own.

import { mergeConfigs } from '@memberjunction/config';

const merged = mergeConfigs(defaults, overrides, {
  concatenateArrays: false,   // true to append arrays instead of replacing
  allowNullOverrides: false   // true to let null values clear defaults
});

Merge Rules

| Source Type | Behavior | |-------------|----------| | Primitive (string, number, boolean) | Override replaces default | | Object | Deep recursive merge | | Array | Override replaces default (or concatenates if concatenateArrays: true) | | null / undefined in override | Ignored by default; replaces if allowNullOverrides: true | | Key with _append suffix | Concatenates the array onto the matching base key |

The _append suffix is especially useful when a user wants to add items to a default array without wiping it out:

// mj.config.cjs
module.exports = {
  // Instead of replacing excludeSchemas entirely, append to the defaults
  excludeSchemas_append: ['staging', 'archive']
};

Validating Configuration Structure

validateConfigStructure checks a merged configuration object against a set of expected top-level keys and logs warnings for any unexpected entries. This helps catch typos and deprecated settings early.

import { validateConfigStructure } from '@memberjunction/config';

const allowedKeys = new Set(['port', 'debug', 'database', 'logging']);
validateConfigStructure(config, allowedKeys);
// Warns: "Unexpected configuration keys found: databse"

Parsing Boolean Environment Variables

parseBooleanEnv normalizes the many string representations of boolean values commonly found in environment variables into a strict true / false.

import { parseBooleanEnv } from '@memberjunction/config';

const debugMode = parseBooleanEnv(process.env.MJ_DEBUG);

Truthy values (case-insensitive): true, 1, yes, y, on, t. Everything else -- including undefined, empty string, and null -- returns false.

API Reference

Functions

loadMJConfig<T>(options?): Promise<LoadConfigResult<T>>

Asynchronously discovers and loads an MJ configuration file, merges it with the provided defaults, and returns the result.

loadMJConfigSync<T>(configPath, options?): T

Synchronously loads a configuration file from an explicit path and merges it with defaults. Does not search the directory tree.

buildMJConfig(packageDefaults, userConfigOverrides?): Record<string, unknown>

Merges default configurations from multiple MJ packages into a single object, then applies optional user overrides.

mergeConfigs<T>(defaults, overrides, options?): T

Deep-merges two plain objects using customizable strategies for arrays, nulls, and the _append suffix convention.

validateConfigStructure(config, allowedKeys): void

Logs warnings for any top-level keys in config that are not present in allowedKeys.

parseBooleanEnv(value): boolean

Parses a string (typically from process.env) into a boolean using common truthy conventions.

isValidConfig(value): value is MJConfig

Type guard that checks whether a value is a non-null object suitable for use as a configuration.

Interfaces

LoadConfigOptions

| Property | Type | Default | Description | |----------|------|---------|-------------| | searchFrom | string | process.cwd() | Directory to start searching for the config file | | requireConfigFile | boolean | false | Throw if no config file is found | | mergeOptions | MergeOptions | {} | Controls array and null merge behavior | | verbose | boolean | false | Log discovery and merge details to console | | defaultConfig | Record<string, unknown> | {} | Base configuration provided by the calling package |

LoadConfigResult<T>

| Property | Type | Description | |----------|------|-------------| | config | T | The final merged configuration | | configFilePath | string \| undefined | Path to the discovered user config file | | hasUserConfig | boolean | Whether a user config file was found | | overriddenKeys | string[] | Top-level keys that differ from defaults |

MergeOptions

| Property | Type | Default | Description | |----------|------|---------|-------------| | concatenateArrays | boolean | false | Append override arrays to defaults instead of replacing | | allowNullOverrides | boolean | false | Allow null in overrides to clear default values |

Types

MJConfig

type MJConfig = Record<string, unknown>;

Generic configuration type. Each consuming package defines its own specific configuration interface.

Architecture

flowchart TB
    subgraph ConfigPackage ["@memberjunction/config"]
        direction TB
        CL["config-loader.ts<br/>loadMJConfig / loadMJConfigSync / buildMJConfig"]
        CM["config-merger.ts<br/>mergeConfigs / validateConfigStructure"]
        CT["config-types.ts<br/>MJConfig / isValidConfig"]
        EU["env-utils.ts<br/>parseBooleanEnv"]
        CL --> CM
    end

    subgraph Consumers ["Consuming Packages"]
        direction TB
        SRV["@memberjunction/server"]
        CG["@memberjunction/codegen-lib"]
        MCP["@memberjunction/mcp-server"]
        A2A["@memberjunction/a2a-server"]
        CLI["@memberjunction/cli"]
        MS["@memberjunction/metadata-sync"]
    end

    Consumers --> ConfigPackage

    style ConfigPackage fill:#2d6a9f,stroke:#1a4971,color:#fff
    style CL fill:#7c5295,stroke:#563a6b,color:#fff
    style CM fill:#7c5295,stroke:#563a6b,color:#fff
    style CT fill:#7c5295,stroke:#563a6b,color:#fff
    style EU fill:#7c5295,stroke:#563a6b,color:#fff
    style Consumers fill:#2d8659,stroke:#1a5c3a,color:#fff
    style SRV fill:#2d8659,stroke:#1a5c3a,color:#fff
    style CG fill:#2d8659,stroke:#1a5c3a,color:#fff
    style MCP fill:#2d8659,stroke:#1a5c3a,color:#fff
    style A2A fill:#2d8659,stroke:#1a5c3a,color:#fff
    style CLI fill:#2d8659,stroke:#1a5c3a,color:#fff
    style MS fill:#2d8659,stroke:#1a5c3a,color:#fff

Dependencies

| Package | Purpose | |---------|---------| | cosmiconfig | Configuration file discovery and loading | | lodash.mergewith | Deep merge with custom merge strategy | | zod | Schema validation (available for consumers) |

Related Packages

| Package | Relationship | |---------|-------------| | @memberjunction/server | Defines MJServerConfig defaults; uses mergeConfigs and parseBooleanEnv | | @memberjunction/codegen-lib | Defines CodeGenConfig defaults; uses mergeConfigs and parseBooleanEnv | | @memberjunction/mcp-server | Defines MCPServerConfig defaults; uses mergeConfigs | | @memberjunction/a2a-server | Defines A2AServerConfig defaults; uses mergeConfigs | | @memberjunction/cli | CLI tool config loading; uses mergeConfigs and parseBooleanEnv | | @memberjunction/metadata-sync | Metadata sync config; uses mergeConfigs and parseBooleanEnv |