Security News
Combatting Alert Fatigue by Prioritizing Malicious Intent
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
cosmiconfig
Advanced tools
Find and load configuration from a package.json property, rc file, or CommonJS module
The cosmiconfig npm package is a utility for finding and loading configuration from a variety of file formats and locations. It is commonly used in Node.js projects to create flexible configuration systems for tools and libraries.
Searching for configuration files
This feature allows you to search for configuration files with a given name in various locations, including package.json properties, rc files, and regular JSON or YAML files.
const cosmiconfig = require('cosmiconfig');
const explorer = cosmiconfig('yourModuleName');
explorer.search()
.then((result) => {
const config = result ? result.config : {};
// do something with config
})
.catch((error) => {
// handle error
});
Loading configuration files directly
This feature allows you to load a configuration file directly from a specified path, regardless of the file's format.
const cosmiconfig = require('cosmiconfig');
const explorer = cosmiconfig('yourModuleName');
explorer.load('/path/to/config').then((result) => {
const config = result ? result.config : {};
// do something with config
}).catch((error) => {
// handle error
});
Creating a custom explorer
This feature allows you to create a custom explorer with specific search places and loaders, enabling you to define where and how configuration files should be found and interpreted.
const cosmiconfig = require('cosmiconfig');
const explorer = cosmiconfig('yourModuleName', {
searchPlaces: ['custom.config.js', 'package.json'],
loaders: {
'.js': cosmiconfig.loadJs,
'.json': cosmiconfig.loadJson
}
});
The 'rc' package is similar to cosmiconfig in that it also searches for and loads configuration files. However, 'rc' focuses on a specific pattern of '.rc' files and does not support as many file formats as cosmiconfig.
The 'config' package is another configuration loader that supports multiple file formats. Unlike cosmiconfig, 'config' is designed for application configuration and has a different approach to file discovery, defaulting to a 'config' directory.
Convict is a configuration management library that includes schema definitions. It is more opinionated than cosmiconfig and includes validation and environment variable support out of the box, which cosmiconfig does not do without additional setup.
Find and load a configuration object from
package.json
property (anywhere down the file tree).config.js
CommonJS module (anywhere down the file tree)--config
argumentFor example, if your module's name is "soursocks," cosmiconfig will search out configuration in the following places:
soursocks
property in package.json
(anywhere down the file tree).soursocksrc
file in JSON or YAML format (anywhere down the file tree)soursocks.config.js
file exporting a JS object (anywhere down the file tree)--config
argumentcosmiconfig continues to search in these places all the way down the file tree until it finds acceptable configuration (or hits the home directory). And it does all this asynchronously, so it shouldn't get in your way.
Additionally, all of these search locations are configurable: you can customize filenames or turn off any location.
npm install cosmiconfig
Tested in Node 0.10+.
var cosmiconfig = require('cosmiconfig');
cosmiconfig(yourModuleName[, options])
.then(function(result) {
// result.config is the parsed configuration object
// result.filepath is the path to the config file that was found
})
.catch(function(parsingError) {
// do something constructive
});
The function cosmiconfig()
searches for a configuration object and returns a Promise,
which resolves with an object containing the information you're looking for.
So let's say var yourModuleName = 'goldengrahams'
— here's how cosmiconfig will work:
process.cwd()
(or some other directory defined by options.cwd
), it looks for configuration objects in three places, in this order:
goldengrahams
property in a package.json
file (or some other property defined by options.packageProp
);.goldengrahamsrc
file with JSON or YAML syntax (or some other filename defined by options.rc
);goldengrahams.config.js
JS file exporting the object (or some other filename defined by options.js
)../
, ../
, ../../
, ../../../
, etc., checking those three locations in each directory.options.stopDir
).cosmiconfig()
Promise resolves with its result object.cosmiconfig()
Promise resolves with null
.cosmiconfig()
Promise rejects and shares that error (so you should .catch()
it).All this searching can be short-circuited by passing options.configPath
or a --config
CLI argument to specify a file.
cosmiconfig will read that file and try parsing it as JSON, YAML, or JS.
Returns a promise that resolves with null
(if no configuration was found) or an object with the following properties:
Type: string
You module name. This is used to create the default filenames that cosmiconfig will look for.
Type: string
or false
Default: '[moduleName]'
Name of the property in package.json
to look for.
If false
, cosmiconfig will not look in package.json
files.
Type: string
or false
Default: '.[moduleName]rc'
Name of the "rc file" to look for, which can be formatted as JSON or YAML.
If false
, cosmiconfig will not look for an rc file.
Type: string
or false
Default: '[moduleName].config.js'
Name of a JS file to look for, which must export the configuration object.
If false
, cosmiconfig will not look for a JS file.
Type: string
or false
Default: 'config'
Name of a process.argv
argument to look for, whose value should be the path to a configuration file.
cosmiconfig will read the file and try to parse it as JSON, YAML, or JS.
By default, cosmiconfig looks for --config
.
If false
, cosmiconfig will not look for any process.argv
arguments.
Type: string
Path to a configuration file. cosmiconfig will read it and try to parse it as JSON, YAML, or JS.
This option can be set via the command line with --config
.
Type: boolean
Default: false
If true
, cosmiconfig will expect rc files to be strict JSON. No YAML permitted, and no sloppy JSON.
By default, rc files are parsed with js-yaml, which is more permissive with punctuation than standard strict JSON.
Type: string
Default: process.cwd()
Directory to start the search from.
Type: string
Default: Absolute path to your home directory
Directory where the search will stop.
rc serves its focused purpose well. cosmiconfig differs in a few key ways — making it more useful for some projects, less useful for others:
package.json
property, an rc file, and a .config.js
file.Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
And please do participate!
1.0.1
FAQs
Find and load configuration from a package.json property, rc file, TypeScript module, and more!
The npm package cosmiconfig receives a total of 55,831,815 weekly downloads. As such, cosmiconfig popularity was classified as popular.
We found that cosmiconfig demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In 2023, data breaches surged 78% from zero-day and supply chain attacks, but developers are still buried under alerts that are unable to prevent these threats.
Security News
Solo open source maintainers face burnout and security challenges, with 60% unpaid and 60% considering quitting.
Security News
License exceptions modify the terms of open source licenses, impacting how software can be used, modified, and distributed. Developers should be aware of the legal implications of these exceptions.