# find-config

> Find the first config file matching a given name in the current directory or the nearest ancestor directory.

Latest version **1.0.0** (published 2016-02-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install find-config
pnpm add find-config
yarn add find-config
bun add find-config
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2016-02-15 |
| First published | 2015-05-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/find-config) |
| Module format | CommonJS |
| Node | >= 0.12 |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 42 |
| Author | Shannon Moeller |
| Maintainers | shannonmoeller |
| Keywords | config, dot, rc, file, find, glob, xdg |

## Links

- npm: https://www.npmjs.com/package/find-config
- Repository: https://github.com/shannonmoeller/find-config
- Issues: https://github.com/shannonmoeller/find-config/issues
- npm.io page: https://npm.io/package/find-config

## Dependencies (1)

- [user-home](https://npm.io/package/user-home.md) ^2.0.0

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2016-02-15
- 0.3.0 — 2015-05-25
- 0.2.0 — 2015-05-07
- 0.1.3 — 2015-05-06
- 0.1.1 — 2015-05-04
- 0.1.0 — 2015-05-04

## README

# `find-config`

[![NPM version][npm-img]][npm-url] [![Downloads][downloads-img]][npm-url] [![Build Status][travis-img]][travis-url] [![Coverage Status][coveralls-img]][coveralls-url] [![Chat][gitter-img]][gitter-url] [![Tip][amazon-img]][amazon-url]

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][xdg] 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][fus] or [look-up][lku].

[fus]: https://www.npmjs.com/package/findup-sync
[lku]: https://www.npmjs.com/package/look-up
[xdg]: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html

## 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](http://nodejs.org):

    $ npm install find-config

## Usage

```js
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][modres]. (Default: `false`)

Synchronously find the first config file matching a given name in the current directory or the nearest ancestor directory.

[modres]: https://nodejs.org/api/modules.html#modules_all_together

### `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.

```js
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`.

```js
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 <me@shannonmoeller.com> (shannonmoeller.com)

Licensed under [MIT](http://shannonmoeller.com/mit.txt)

[amazon-img]:    https://img.shields.io/badge/amazon-tip_jar-yellow.svg?style=flat-square
[amazon-url]:    https://www.amazon.com/gp/registry/wishlist/1VQM9ID04YPC5?sort=universal-price
[coveralls-img]: http://img.shields.io/coveralls/shannonmoeller/find-config/master.svg?style=flat-square
[coveralls-url]: https://coveralls.io/r/shannonmoeller/find-config
[downloads-img]: http://img.shields.io/npm/dm/find-config.svg?style=flat-square
[gitter-img]:    http://img.shields.io/badge/gitter-join_chat-1dce73.svg?style=flat-square
[gitter-url]:    https://gitter.im/shannonmoeller/shannonmoeller
[npm-img]:       http://img.shields.io/npm/v/find-config.svg?style=flat-square
[npm-url]:       https://npmjs.org/package/find-config
[travis-img]:    http://img.shields.io/travis/shannonmoeller/find-config.svg?style=flat-square
[travis-url]:    https://travis-ci.org/shannonmoeller/find-config

---
_Source: https://npm.io/package/find-config · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._