find-config
Finds the first matching config file, if any, in the current directory, nearest ancestor, or user's home directory. Supports finding files within a subdirectory of an ancestor directory. Configurable with defaults set to support the XDG Base Directory Specification for configuration files.
Because this module is intended to find consistently named configuration files, it is case-sensitive and does not support globs. If you need a more generic solution, see findup-sync or look-up.
Algorithm
Where X is the current directory:
- If X/file.ext exists, return it. STOP
- If X/.dir/file.ext exists, return it. STOP
- If X has a parent directory, change X to parent. GO TO 1
- Return NULL.
Install
With Node.js:
$ npm install find-config
Usage
var findConfig = ; // Find the path to the nearest `package.json`var pkg = ; // Find the path to the nearest `.foorc` or `.config/foorc`var foo = ; // Find the path to the nearest `.foorc` or `.config/.foorc`var foo = ; // Find the path to the nearest module using Node.js module resolution.// Will look for `bar.js` or `bar/index.js`, etc.var foo = ; // Find the path to the nearest `baz.json` or `some/path/baz.json`var foo = ; // Find the path to the nearest `qux.json` or `some/path/qux.json` in// some other directory or its nearest ancestor directory.var foo = ; // Find and require the nearest `package.json`var pkg = findConfig; // Find and read the nearest `.foorc` or `.config/foorc`var foo = findConfig;
API
findConfig(filename, [options]) : String|Null
filename
String
- Name of the configuration file to find.options
{Object=}
cwd
{String=}
- Directory in which to start looking. (Default:process.cwd()
)dir
{String=}
- An optional subdirectory to check at each level. (Default:'.config'
)dot
{Boolean=}
- Whether to keep the leading dot in the filename indir
. (Default:false
)home
{Boolean=}
- Whether to also check the user's home directory. (Default:true
)module
{Boolean=}
- Whether to use Node.js module resolution. (Default:false
)
Synchronously find the first config file matching a given name in the current directory or the nearest ancestor directory.
findConfig.obj(filename, [options]) : Object|Null
filename
String
- Name of the configuration file to find.options
{Object=}
- Same asfindConfig()
.
Finds first matching config file, if any and returns the matched directories and config file path.
findConfig.read(filename, [options]) : String|Null
filename
String
- Name of the configuration file to find.options
{Object=}
- Same asfindConfig()
with two additions.encoding
{String}
- File encoding. (Default:'utf8'
).flag
{String}
- Flag. (Default:'r'
).
Finds and reads the first matching config file, if any.
var yaml = ;var travis = yaml;
findConfig.require(filename, [options]) : *
filename
String
- Name of the configuration file to find.options
{Object=}
- Same asfindConfig()
.
Finds and requires the first matching config file, if any. Implies module
is true
.
var version = findConfigversion;
Contribute
Standards for this project, including tests, code coverage, and semantics are enforced with a build tool. Pull requests must include passing tests with 100% code coverage and no linting errors.
Test
$ npm test
© Shannon Moeller me@shannonmoeller.com (shannonmoeller.com)
Licensed under MIT