npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

configr8

v1.0.0-rc.0

Published

.rc-style configuration files for node

Downloads

19

Readme

Configr8

It is useful to be able to provide a basic configuration with overrides based on system, runtime, user, environment, and other factors. .{name}rc files provide a solid foundation for such configurations. Configr8 provides an API modeled loosely after rc and yargs, with a few helpful additions and potentially arbitrary quirks and opinions (discerning between these is left as an exercise for the reader.)

File Locations

Configr8 will look for and apply configuration files from the locations specified by the patterns key in the settings you give it. It provides two named pattern sets which should meet most use cases - which you refer to by setting patterns to their name, but you can also provide your own array of patterns.

The two named pattern sets are:

"application"

The "application" patterns are appropriate for configuring an application. This is the default.

[
    "${home}/.${name}rc",
    "${cwd}/.${name}rc",
    "${etc}/${name}rc",
]

"per-directory"

The "per-directory" patterns are appropriate for configuring a tool that should act differently in different target directories.

[
    "${parents}/.${name}rc",
    "${home}/.${name}rc",
    "${etc}/${name}rc"
]

The tokens in these patterns are substituted as follows:

  • ${name} - the name string specified in settings. In all cases where a - is found in the ${name} an additional - will be inserted before any appended rc suffix. That is, files will be expected to be .hyphenated-app-name-rc rather than .hyphenated-app-namerc.
  • ${home} - the current user's HOME directory or the home path specified in settings
  • ${cwd} - the process' current working directory or the cwd path specified in settings
  • ${etc} - the etc path specified in settings
  • ${parents} - like ${cwd} except that it checks each parent of the current working directory back to the root of the file system.

Environment and Default Configuration Files

Additionally, these same file locations will be searched for environment-specific files, substituting ${name}-${environment}- for ${name} in the patterns above. The environment searched for will be determined, in order of precedence, by the env or environment command line arguments (if parsed), the env or environment properties of any overrides passed in, or the ${name}_ENV, ENV, NODE_ENV, or ENVIRONMENT environment variables. If none of these is found, no environment-specific files will be loaded.

Similarly, these same filesystem locations will be searched for "defaults" files using ${name}-defaults- instead of ${name}.

Merging configuration

Configuration defaults are merged by first taking the values under the :defaults: key in any standard configuration files, then configuration from any defaults configuration files, then the values under the :defaults: key in any environment specific configuration files.

Environment specific configurations are merged with values under the [":env:"][environment] key path from any defaults configuration files, then values under the [":env:"][environment] key path from any standard configuration files, and finally the values in any environment specific configuration files.

Finally, the merged configuration defaults are overriden by the merged standard configuration, which is further overriden by the merged environment specific configuration.

The defaults object you pass in will be treated as the lowest priority defaults configuration file.

Configuration from environment varibles, overrides you pass in, and configuration from parsed command line arguments is then merged in order, giving command line arguments the highest precedence. These configuration sources do not provide a mechanism for specifying defaults or environment specific configuration because it is not needed.

Configuring Configr8

Configr8 exports a (synchronous) function that allows you to provide settings describing how Configr8 should work. This will either be an app name string or an object containing an name property and other meta-configuration parameters. This function will return a configuration resolver function.

Settings

  • name - Required. This is the name that will be used to look up configurtion files and environment variables, etc.
  • useArgv - Default: false. Indicates whether Configr8 should parse process.argv for configuration. Default is false because users will often pass in overrides from their own argv parser (or another source).
  • useEnv - Default: true. Indicates whether Configr8 should parse process.env for configuration.
  • usePkg - Default: true. Indicates whether Configr8 should parse package.json and get configuration from the key matching name.
  • cwd - Default: process.cwd(). The path Configr8 should treat as the target or current working directory. It does not actually change process.cwd().
  • home - Default: The user's home directory as determined by os-homedir. The path Configr8 should treat as the user's home directory.
  • etc - Default: null. The path Configr8 should treat as the system configuration directory.
  • patterns - Default: "application". The set of patterns to use to search for configuration files. (See File Locations above for details).
  • async - Default: false. Indicates whether Configr8's configuration resolver function should return a Promise if no callback function is provided. When false and no callback is provided the configuration resolver function will return the resolved configuration or an Error synchronously.

Installation

> npm install configr8 --save

Use

var configResolver = require('configr8')('my-app');

var defaultConfig = {
	fiz: 'buzz',
	blah: {
		blarg: 2,
		biz: 1
	}
};

var config = configResolver(defaultConfig);

//...