find-config

What is find-config?

The find-config npm package is a utility for locating configuration files in a project. It searches for configuration files by traversing up the directory tree from a given starting point, making it easier to manage and locate configuration files in complex project structures.

What are find-config's main functionalities?

Find a specific configuration file

This feature allows you to find a specific configuration file (e.g., 'config.json') by searching up the directory tree from the current working directory.

const findConfig = require('find-config');
const configPath = findConfig('config.json');
console.log(configPath);

Find a configuration file from a specific directory

This feature allows you to specify a starting directory for the search, rather than using the current working directory.

const findConfig = require('find-config');
const configPath = findConfig('config.json', { cwd: '/path/to/start' });
console.log(configPath);

Find the first configuration file from a list of possible names

This feature allows you to search for the first configuration file that matches any name in a list of possible names.

const findConfig = require('find-config');
const configPath = findConfig(['config.json', 'config.yaml', 'config.js']);
console.log(configPath);

Other packages similar to find-config

cosmiconfig

Cosmiconfig is a more feature-rich configuration file loader that supports multiple file formats (JSON, YAML, JS, etc.) and allows for more complex configuration file resolution strategies. It also supports caching and custom loaders, making it more flexible than find-config.

rc

The rc package is a simple configuration loader that looks for configuration files in a variety of locations, including environment variables, command-line arguments, and configuration files in the user's home directory. It is more focused on loading configuration values rather than just locating configuration files.

config

The config package provides a more structured approach to managing configuration files, supporting different environments (development, production, etc.) and allowing for configuration file inheritance. It is more comprehensive than find-config in terms of managing and organizing configuration data.

README

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:

1. If X/file.ext exists, return it. STOP
2. If X/.dir/file.ext exists, return it. STOP
3. If X has a parent directory, change X to parent. GO TO 1
4. Return NULL.

Install

With Node.js:

$ npm install find-config

Usage

var findConfig = require('find-config');

// Find the path to the nearest `package.json`
var pkg = findConfig('package.json');

// Find the path to the nearest `.foorc` or `.config/foorc`
var foo = findConfig('.foorc');

// Find the path to the nearest `.foorc` or `.config/.foorc`
var foo = findConfig('.foorc', { dot: true });

// Find the path to the nearest module using Node.js module resolution.
// Will look for `bar.js` or `bar/index.js`, etc.
var foo = findConfig('bar', { module: true });

// Find the path to the nearest `baz.json` or `some/path/baz.json`
var foo = findConfig('baz.json', { dir: 'some/path' });

// Find the path to the nearest `qux.json` or `some/path/qux.json` in
// some other directory or its nearest ancestor directory.
var foo = findConfig('qux.json', { cwd: '/other/dir', dir: 'some/path' });

// Find and require the nearest `package.json`
var pkg = findConfig.require('package.json');

// Find and read the nearest `.foorc` or `.config/foorc`
var foo = findConfig.read('.foorc');

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 in dir. (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 as findConfig().

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 as findConfig() 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 = require('js-yaml');
var travis = yaml.safeLoad(findConfig.read('.travis.yml'));

findConfig.require(filename, [options]) : *

• filename String - Name of the configuration file to find.
• options {Object=} - Same as findConfig().

Finds and requires the first matching config file, if any. Implies module is true.

var version = findConfig.require('package.json').version;

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 [e-mail] (shannonmoeller.com)

Licensed under MIT