@mrbuilder/optionsmanager v4.4.7-alpha.9

The OptionsManager is a babel inspired configuration system for plugin based apps. It is generic in the since it can be configured to use different namespaces. It handles command line args, env args, and file based configuration.

Theory

A method for enabling, discovering plugins is required in many apps, particularly in mono repos, where there may be many many plugins. This optionsmanager provides infrastructure for describing the configuration and loading of said plugins. Its meant to be declarative, to allow for easy modification and overriding.

It searches for a "plugins" or "presets" in a section named ${prefix} in package.json or .${prefix}rc in addition it searches the ENV for ${envPrefix}_PLUGINS, ${envPrefix}_PRESETS and after evaluation it search ${envPrefix}_INTERNAL_PRESETS

Presets vs Plugins

All plugins within a preset will get the configuration. Presets do not get evaluated only searched, so if a project needs another projects presets the originating project can include it as a preset. As it is not a plugin ) but it uses plugins this should add some convenience.

Presets

Presets are a collection of configured plugins. The follow the same env resolution protocol as plugins

${envPrefix}_ENV -

Defaults to NODE_ENV if it is null. This tells the option manager which env the user, and therefore configuration the app is running with. Because NODE_ENV is conventionally used for test,development,production, but configurations often have more ENV's this allows for more specific configuration for an environment. I.E. a server build may be env production:server but the node env would need to be production for downstream tools to work correctly.

Configuration

const optionsManager = new OptionsManager({prefix:'whatever'});

• prefix - the prefix to use for internal ie.mrbuilder
• envPrefix - the environment prefix to use, defaults to prefix.toUpperCase();
• confPrefix - the prefix to configure things.
• rcFile - the rc file to use for preferences, uses .${prefix}rc as default.
• env - the environment default to process.env
• argv - the arguments array defaults to process.argv;
• cwd - A function returning current working dir defaults to process.cwd,
• info - A function for logging info level console.info || console.warn,
• debug - A function for logging debug level defaults console.info || console.warn,
• warn - A function for logging warn level console.warn,
• _require - A require function useful for scripts require,
• aliasObj - Alias's you want to pass
• handleNotFound - Function to call when a package is not found.

Resolution

Plugins resolve from the plugins array first, than the env.ENV.plugins array. If a plugin exists in both arrays it will use the configuration of the env.ENV.plugins array. If no configuration is given for env.ENV.plugins than no configuration will be passed to the plugin. If a plugin in env.ENV.plugins second argument is false than it will be disabled.

Options passed as Environmental variables.

To pass an option from the environment to a plugin, their are 2 options. First pass a stringified object to the env variable such as

export MRBUILDER_PLUGIN_EXAMPLE="{\"moreStuff\":1}" 

Or to pass individual options, use __ to seperate plugin name and key names.

export MRBUILDER_PLUGIN_EXAMPLE__MORE_STUFF="1";