\href{https://travis-ci.org/davidtheclark/cosmiconfig}{\texttt{ }} \href{https://ci.appveyor.com/project/davidtheclark/cosmiconfig/branch/master}{\texttt{ }} \href{https://codecov.io/gh/davidtheclark/cosmiconfig}{\texttt{ }}

Cosmiconfig searches for and loads configuration for your program.

It features smart defaults based on conventional expectations in the Java\+Script ecosystem. But it\textquotesingle{}s also flexible enough to search wherever you\textquotesingle{}d like to search, and load whatever you\textquotesingle{}d like to load.

By default, Cosmiconfig will start where you tell it to start and search up the directory tree for the following\+:


\begin{DoxyItemize}
\item a {\ttfamily package.\+json} property
\item a JSON or YAML, extensionless \char`\"{}rc file\char`\"{}
\item an \char`\"{}rc file\char`\"{} with the extensions {\ttfamily .json}, {\ttfamily .yaml}, {\ttfamily .yml}, or {\ttfamily .js}.
\item a {\ttfamily .config.\+js} Common\+JS module
\end{DoxyItemize}

For example, if your module\textquotesingle{}s name is \char`\"{}soursocks\char`\"{}, cosmiconfig will search up the directory tree for configuration in the following places\+:


\begin{DoxyItemize}
\item a {\ttfamily soursocks} property in {\ttfamily package.\+json}
\item a {\ttfamily .soursocksrc} file in JSON or YAML format
\item a {\ttfamily .soursocksrc.\+json} file
\item a {\ttfamily .soursocksrc.\+yaml}, {\ttfamily .soursocksrc.\+yml}, or {\ttfamily .soursocksrc.\+js} file
\item a {\ttfamily soursocks.\+config.\+js} file exporting a JS object
\end{DoxyItemize}

Cosmiconfig continues to search up the directory tree, checking each of these places in each directory, until it finds some acceptable configuration (or hits the home directory).

👀 {\bfseries{Looking for the v4 docs?}} v5 involves significant revisions to Cosmiconfig\textquotesingle{}s API, allowing for much greater flexibility and clarifying some things. If you have trouble switching from v4 to v5, please file an issue. If you are still using v4, those v4 docs are available \href{https://github.com/davidtheclark/cosmiconfig/tree/4.0.0}{\texttt{ in the {\ttfamily 4.\+0.\+0} tag}}.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6800}{}\doxysection{Table of contents}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6800}

\begin{DoxyItemize}
\item \href{\#installation}{\texttt{ Installation}}
\item \href{\#usage}{\texttt{ Usage}}
\item \href{\#result}{\texttt{ Result}}
\item \href{\#cosmiconfig-1}{\texttt{ cosmiconfig()}}
\begin{DoxyItemize}
\item \href{\#modulename}{\texttt{ module\+Name}}
\end{DoxyItemize}
\item \href{\#explorersearch}{\texttt{ explorer.\+search()}}
\begin{DoxyItemize}
\item \href{\#searchfrom}{\texttt{ search\+From}}
\end{DoxyItemize}
\item \href{\#explorersearchsync}{\texttt{ explorer.\+search\+Sync()}}
\item \href{\#explorerload}{\texttt{ explorer.\+load()}}
\item \href{\#explorerloadsync}{\texttt{ explorer.\+load\+Sync()}}
\item \href{\#explorerclearloadcache}{\texttt{ explorer.\+clear\+Load\+Cache()}}
\item \href{\#explorerclearsearchcache}{\texttt{ explorer.\+clear\+Search\+Cache()}}
\item \href{\#explorerclearcaches}{\texttt{ explorer.\+clear\+Caches()}}
\item \href{\#cosmiconfigoptions}{\texttt{ cosmiconfig\+Options}}
\begin{DoxyItemize}
\item \href{\#searchplaces}{\texttt{ search\+Places}}
\item \href{\#loaders}{\texttt{ loaders}}
\item \href{\#packageprop}{\texttt{ package\+Prop}}
\item \href{\#stopdir}{\texttt{ stop\+Dir}}
\item \href{\#cache}{\texttt{ cache}}
\item \href{\#transform}{\texttt{ transform}}
\item \href{\#ignoreemptysearchplaces}{\texttt{ ignore\+Empty\+Search\+Places}}
\end{DoxyItemize}
\item \href{\#caching}{\texttt{ Caching}}
\item \href{\#differences-from-rc}{\texttt{ Differences from rc}}
\item \href{\#contributing--development}{\texttt{ Contributing \& Development}}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6801}{}\doxysection{Installation}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6801}

\begin{DoxyCode}{0}
\DoxyCodeLine{npm install cosmiconfig }

\end{DoxyCode}


Tested in Node 4+.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6802}{}\doxysection{Usage}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6802}
Create a Cosmiconfig explorer, then either {\ttfamily search} for or directly {\ttfamily load} a configuration file.


\begin{DoxyCode}{0}
\DoxyCodeLine{const cosmiconfig = require('cosmiconfig');}
\DoxyCodeLine{// ...}
\DoxyCodeLine{const explorer = cosmiconfig(moduleName);}
\DoxyCodeLine{}
\DoxyCodeLine{// Search for a configuration by walking up directories.}
\DoxyCodeLine{// See documentation for search, below.}
\DoxyCodeLine{explorer.search()}
\DoxyCodeLine{  .then((result) => \{}
\DoxyCodeLine{    // result.config is the parsed configuration object.}
\DoxyCodeLine{    // result.filepath is the path to the config file that was found.}
\DoxyCodeLine{    // result.isEmpty is true if there was nothing to parse in the config file.}
\DoxyCodeLine{  \})}
\DoxyCodeLine{  .catch((error) => \{}
\DoxyCodeLine{    // Do something constructive.}
\DoxyCodeLine{  \});}
\DoxyCodeLine{}
\DoxyCodeLine{// Load a configuration directly when you know where it should be.}
\DoxyCodeLine{// The result object is the same as for search.}
\DoxyCodeLine{// See documentation for load, below.}
\DoxyCodeLine{explorer.load(pathToConfig).then(..);}
\DoxyCodeLine{}
\DoxyCodeLine{// You can also search and load synchronously.}
\DoxyCodeLine{const searchedFor = explorer.searchSync();}
\DoxyCodeLine{const loaded = explorer.loadSync(pathToConfig); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6803}{}\doxysection{Result}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6803}
The result object you get from {\ttfamily search} or {\ttfamily load} has the following properties\+:


\begin{DoxyItemize}
\item {\bfseries{config\+:}} The parsed configuration object. {\ttfamily undefined} if the file is empty.
\item {\bfseries{filepath\+:}} The path to the configuration file that was found.
\item {\bfseries{is\+Empty\+:}} {\ttfamily true} if the configuration file is empty. This property will not be present if the configuration file is not empty.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6804}{}\doxysection{cosmiconfig()}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6804}

\begin{DoxyCode}{0}
\DoxyCodeLine{const explorer = cosmiconfig(moduleName[, cosmiconfigOptions]) }

\end{DoxyCode}


Creates a cosmiconfig instance (\char`\"{}explorer\char`\"{}) configured according to the arguments, and initializes its caches.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6805}{}\doxysubsection{module\+Name}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6805}
Type\+: {\ttfamily string}. {\bfseries{Required.}}

Your module name. This is used to create the default \href{\#searchplaces}{\texttt{ {\ttfamily search\+Places}}} and \href{\#packageprop}{\texttt{ {\ttfamily package\+Prop}}}.

$\ast$$\ast$\href{\#cosmiconfigoptions}{\texttt{ {\ttfamily cosmiconfig\+Options}}} are documented below.$\ast$$\ast$ You may not need them, and should first read about the functions you\textquotesingle{}ll use.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6806}{}\doxysection{explorer.\+search()}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6806}

\begin{DoxyCode}{0}
\DoxyCodeLine{explorer.search([searchFrom]).then(result => \{..\}) }

\end{DoxyCode}


Searches for a configuration file. Returns a Promise that resolves with a \href{\#result}{\texttt{ result}} or with {\ttfamily null}, if no configuration file is found.

You can do the same thing synchronously with \href{\#explorersearchsync}{\texttt{ {\ttfamily search\+Sync()}}}.

Let\textquotesingle{}s say your module name is {\ttfamily goldengrahams} so you initialized with `const explorer = cosmiconfig(\textquotesingle{}goldengrahams');{\ttfamily . Here\textquotesingle{}s how your default \mbox{[}}search()\`{}\mbox{]} will work\+:


\begin{DoxyItemize}
\item Starting from {\ttfamily process.\+cwd()} (or some other directory defined by the {\ttfamily search\+From} argument to \href{\#explorersearch}{\texttt{ {\ttfamily search()}}}), look for configuration objects in the following places\+:
\begin{DoxyEnumerate}
\item A {\ttfamily goldengrahams} property in a {\ttfamily package.\+json} file.
\item A {\ttfamily .goldengrahamsrc} file with JSON or YAML syntax.
\item A {\ttfamily .goldengrahamsrc.\+json} file.
\item A {\ttfamily .goldengrahamsrc.\+yaml}, {\ttfamily .goldengrahamsrc.\+yml}, or {\ttfamily .goldengrahamsrc.\+js} file.
\item A {\ttfamily goldengrahams.\+config.\+js} JS file exporting the object.
\end{DoxyEnumerate}
\item If none of those searches reveal a configuration object, move up one directory level and try again. So the search continues in {\ttfamily ./}, {\ttfamily ../}, {\ttfamily ../../}, {\ttfamily ../../../}, etc., checking the same places in each directory.
\item Continue searching until arriving at your home directory (or some other directory defined by the cosmiconfig option \href{\#stopdir}{\texttt{ {\ttfamily stop\+Dir}}}).
\item If at any point a parseable configuration is found, the \href{\#explorersearch}{\texttt{ {\ttfamily search()}}} Promise resolves with its \href{\#result}{\texttt{ result}} (or, with \href{\#explorersearchsync}{\texttt{ {\ttfamily search\+Sync()}}}, the \href{\#result}{\texttt{ result}} is returned).
\item If no configuration object is found, the \href{\#explorersearch}{\texttt{ {\ttfamily search()}}} Promise resolves with {\ttfamily null} (or, with \href{\#explorersearchsync}{\texttt{ {\ttfamily search\+Sync()}}}, {\ttfamily null} is returned).
\item If a configuration object is found {\itshape but is malformed} (causing a parsing error), the \href{\#explorersearch}{\texttt{ {\ttfamily search()}}} Promise rejects with that error (so you should {\ttfamily .catch()} it). (Or, with \href{\#explorersearchsync}{\texttt{ {\ttfamily search\+Sync()}}}, the error is thrown.)
\end{DoxyItemize}

$\ast$$\ast$\+If you know exactly where your configuration file should be, you can use \href{\#explorerload}{\texttt{ {\ttfamily load()}}}, instead.$\ast$$\ast$

{\bfseries{The search process is highly customizable.}} Use the cosmiconfig options \href{\#searchplaces}{\texttt{ {\ttfamily search\+Places}}} and \href{\#loaders}{\texttt{ {\ttfamily loaders}}} to precisely define where you want to look for configurations and how you want to load them.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6807}{}\doxysubsection{search\+From}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6807}
Type\+: {\ttfamily string}. Default\+: {\ttfamily process.\+cwd()}.

A filename. \href{\#explorersearch}{\texttt{ {\ttfamily search()}}} will start its search here.

If the value is a directory, that\textquotesingle{}s where the search starts. If it\textquotesingle{}s a file, the search starts in that file\textquotesingle{}s directory.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6808}{}\doxysection{explorer.\+search\+Sync()}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6808}

\begin{DoxyCode}{0}
\DoxyCodeLine{const result = explorer.searchSync([searchFrom]); }

\end{DoxyCode}


Synchronous version of \href{\#explorersearch}{\texttt{ {\ttfamily search()}}}.

Returns a \href{\#result}{\texttt{ result}} or {\ttfamily null}.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6809}{}\doxysection{explorer.\+load()}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6809}

\begin{DoxyCode}{0}
\DoxyCodeLine{explorer.load(loadPath).then(result => \{..\}) }

\end{DoxyCode}


Loads a configuration file. Returns a Promise that resolves with a \href{\#result}{\texttt{ result}} or rejects with an error (if the file does not exist or cannot be loaded).

Use {\ttfamily load} if you already know where the configuration file is and you just need to load it.


\begin{DoxyCode}{0}
\DoxyCodeLine{explorer.load('load/this/file.json'); // Tries to load load/this/file.json. }

\end{DoxyCode}


If you load a {\ttfamily package.\+json} file, the result will be derived from whatever property is specified as your \href{\#packageprop}{\texttt{ {\ttfamily package\+Prop}}}.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6810}{}\doxysection{explorer.\+load\+Sync()}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6810}

\begin{DoxyCode}{0}
\DoxyCodeLine{const result = explorer.loadSync(loadPath); }

\end{DoxyCode}


Synchronous version of \href{\#explorerload}{\texttt{ {\ttfamily load()}}}.

Returns a \href{\#result}{\texttt{ result}}.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6811}{}\doxysection{explorer.\+clear\+Load\+Cache()}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6811}
Clears the cache used in \href{\#explorerload}{\texttt{ {\ttfamily load()}}}.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6812}{}\doxysection{explorer.\+clear\+Search\+Cache()}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6812}
Clears the cache used in \href{\#explorersearch}{\texttt{ {\ttfamily search()}}}.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6813}{}\doxysection{explorer.\+clear\+Caches()}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6813}
Performs both \href{\#explorerclearloadcache}{\texttt{ {\ttfamily clear\+Load\+Cache()}}} and \href{\#explorerclearsearchcache}{\texttt{ {\ttfamily clear\+Search\+Cache()}}}.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6814}{}\doxysection{cosmiconfig\+Options}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6814}
Type\+: {\ttfamily Object}.

Possible options are documented below.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6815}{}\doxysubsection{search\+Places}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6815}
Type\+: {\ttfamily Array$<$string$>$}. Default\+: See below.

An array of places that \href{\#explorersearch}{\texttt{ {\ttfamily search()}}} will check in each directory as it moves up the directory tree. Each place is relative to the directory being searched, and the places are checked in the specified order.

{\bfseries{Default {\ttfamily search\+Places}\+:}}


\begin{DoxyCode}{0}
\DoxyCodeLine{[}
\DoxyCodeLine{  'package.json',}
\DoxyCodeLine{  `.\$\{moduleName\}rc`,}
\DoxyCodeLine{  `.\$\{moduleName\}rc.json`,}
\DoxyCodeLine{  `.\$\{moduleName\}rc.yaml`,}
\DoxyCodeLine{  `.\$\{moduleName\}rc.yml`,}
\DoxyCodeLine{  `.\$\{moduleName\}rc.js`,}
\DoxyCodeLine{  `\$\{moduleName\}.config.js`,}
\DoxyCodeLine{] }

\end{DoxyCode}


Create your own array to search more, fewer, or altogether different places.

Every item in {\ttfamily search\+Places} needs to have a loader in \href{\#loaders}{\texttt{ {\ttfamily loaders}}} that corresponds to its extension. (Common extensions are covered by default loaders.) Read more about \href{\#loaders}{\texttt{ {\ttfamily loaders}}} below.

{\ttfamily package.\+json} is a special value\+: When it is included in {\ttfamily search\+Places}, Cosmiconfig will always parse it as JSON and load a property within it, not the whole file. That property is defined with the \href{\#packageprop}{\texttt{ {\ttfamily package\+Prop}}} option, and defaults to your module name.

Examples, with a module named {\ttfamily porgy}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{// Disallow extensions on rc files:}
\DoxyCodeLine{[}
\DoxyCodeLine{  'package.json',}
\DoxyCodeLine{  '.porgyrc',}
\DoxyCodeLine{  'porgy.config.js'}
\DoxyCodeLine{]}
\DoxyCodeLine{}
\DoxyCodeLine{// ESLint searches for configuration in these places:}
\DoxyCodeLine{[}
\DoxyCodeLine{  '.eslintrc.js',}
\DoxyCodeLine{  '.eslintrc.yaml',}
\DoxyCodeLine{  '.eslintrc.yml',}
\DoxyCodeLine{  '.eslintrc.json',}
\DoxyCodeLine{  '.eslintrc',}
\DoxyCodeLine{  'package.json'}
\DoxyCodeLine{]}
\DoxyCodeLine{}
\DoxyCodeLine{// Babel looks in fewer places:}
\DoxyCodeLine{[}
\DoxyCodeLine{  'package.json',}
\DoxyCodeLine{  '.babelrc'}
\DoxyCodeLine{]}
\DoxyCodeLine{}
\DoxyCodeLine{// Maybe you want to look for a wide variety of JS flavors:}
\DoxyCodeLine{[}
\DoxyCodeLine{  'porgy.config.js',}
\DoxyCodeLine{  'porgy.config.mjs',}
\DoxyCodeLine{  'porgy.config.ts',}
\DoxyCodeLine{  'porgy.config.coffee'}
\DoxyCodeLine{]}
\DoxyCodeLine{// \string^\string^ You will need to designate custom loaders to tell}
\DoxyCodeLine{// Cosmiconfig how to handle these special JS flavors.}
\DoxyCodeLine{}
\DoxyCodeLine{// Look within a .config/ subdirectory of every searched directory:}
\DoxyCodeLine{[}
\DoxyCodeLine{  'package.json',}
\DoxyCodeLine{  '.porgyrc',}
\DoxyCodeLine{  '.config/.porgyrc',}
\DoxyCodeLine{  '.porgyrc.json',}
\DoxyCodeLine{  '.config/.porgyrc.json'}
\DoxyCodeLine{] }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6816}{}\doxysubsection{loaders}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6816}
Type\+: {\ttfamily Object}. Default\+: See below.

An object that maps extensions to the loader functions responsible for loading and parsing files with those extensions.

Cosmiconfig exposes its default loaders for {\ttfamily .js}, {\ttfamily .json}, and {\ttfamily .yaml} as {\ttfamily cosmiconfig.\+load\+Js}, {\ttfamily cosmiconfig.\+load\+Json}, and {\ttfamily cosmiconfig.\+load\+Yaml}, respectively.

{\bfseries{Default {\ttfamily loaders}\+:}}


\begin{DoxyCode}{0}
\DoxyCodeLine{\{}
\DoxyCodeLine{  '.json': cosmiconfig.loadJson,}
\DoxyCodeLine{  '.yaml': cosmiconfig.loadYaml,}
\DoxyCodeLine{  '.yml': cosmiconfig.loadYaml,}
\DoxyCodeLine{  '.js': cosmiconfig.loadJs,}
\DoxyCodeLine{  noExt: cosmiconfig.loadYaml}
\DoxyCodeLine{\} }

\end{DoxyCode}


(YAML is a superset of JSON;~which means YAML parsers can parse JSON;~which is how extensionless files can be either YAML {\itshape or} JSON with only one parser.)

{\bfseries{If you provide a {\ttfamily loaders} object, your object will be {\itshape merged} with the defaults.}} So you can override one or two without having to override them all.

{\bfseries{Keys in {\ttfamily loaders}}} are extensions (starting with a period), or {\ttfamily no\+Ext} to specify the loader for files {\itshape without} extensions, like {\ttfamily .soursocksrc}.

{\bfseries{Values in {\ttfamily loaders}}} are either a loader function (described below) or an object with {\ttfamily sync} and/or {\ttfamily async} properties, whose values are loader functions.

{\bfseries{The most common use case for custom loaders value is to load extensionless {\ttfamily rc} files as strict JSON}}, instead of JSON {\itshape or} YAML (the default). To accomplish that, provide the following {\ttfamily loaders} value\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\{}
\DoxyCodeLine{  noExt: cosmiconfig.loadJson}
\DoxyCodeLine{\} }

\end{DoxyCode}


If you want to load files that are not handled by the loader functions Cosmiconfig exposes, you can write a custom loader function or use one from NPM if it exists.

{\bfseries{Third-\/party loaders\+:}}


\begin{DoxyItemize}
\item \href{https://github.com/EndemolShineGroup/cosmiconfig-typescript-loader}{\texttt{ @endemolshinegroup/cosmiconfig-\/typescript-\/loader}}
\end{DoxyItemize}

{\bfseries{Use cases for custom loader function\+:}}


\begin{DoxyItemize}
\item Allow configuration syntaxes that aren\textquotesingle{}t handled by Cosmiconfig\textquotesingle{}s defaults, like JSON5, INI, or XML.
\item Allow ES2015 modules from {\ttfamily .mjs} configuration files.
\item Parse JS files with Babel before deriving the configuration.
\end{DoxyItemize}

{\bfseries{Custom loader functions}} have the following signature\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{// Sync}
\DoxyCodeLine{(filepath: string, content: string) => Object | null}
\DoxyCodeLine{}
\DoxyCodeLine{// Async}
\DoxyCodeLine{(filepath: string, content: string) => Object | null | Promise<Object | null> }

\end{DoxyCode}


Cosmiconfig reads the file when it checks whether the file exists, so it will provide you with both the file\textquotesingle{}s path and its content. Do whatever you need to, and return either a configuration object or {\ttfamily null} (or, for async-\/only loaders, a Promise that resolves with one of those). {\ttfamily null} indicates that no real configuration was found and the search should continue.

It\textquotesingle{}s easiest if you make your custom loader function synchronous. Then it can be used regardless of whether you end up calling \href{\#explorersearch}{\texttt{ {\ttfamily search()}}} or \href{\#explorersearchsync}{\texttt{ {\ttfamily search\+Sync()}}}, \href{\#explorerload}{\texttt{ {\ttfamily load()}}} or \href{\#explorerloadsync}{\texttt{ {\ttfamily load\+Sync()}}}. If you want or need to provide an async-\/only loader, you can do so by making the value of {\ttfamily loaders} an object with an {\ttfamily async} property whose value is the async loader. You can also add a {\ttfamily sync} property to designate a sync loader, if you want to use both async and sync search and load functions.

A few things to note\+:


\begin{DoxyItemize}
\item If you use a custom loader, be aware of whether it\textquotesingle{}s sync or async and how that aligned with your usage of sync or async search and load functions.
\item {\bfseries{Special JS syntax can also be handled by using a {\ttfamily require} hook}}, because {\ttfamily cosmiconfig.\+load\+Js} just uses {\ttfamily require}. Whether you use custom loaders or a {\ttfamily require} hook is up to you.
\end{DoxyItemize}

Examples\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{// Allow JSON5 syntax:}
\DoxyCodeLine{\{}
\DoxyCodeLine{  '.json': json5Loader}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{// Allow XML, and treat sync and async separately:}
\DoxyCodeLine{\{}
\DoxyCodeLine{  '.xml': \{ async: asyncXmlLoader, sync: syncXmlLoader \}}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{// Allow a special configuration syntax of your own creation:}
\DoxyCodeLine{\{}
\DoxyCodeLine{  '.special': specialLoader}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{// Allow many flavors of JS, using custom loaders:}
\DoxyCodeLine{\{}
\DoxyCodeLine{  '.mjs': esmLoader,}
\DoxyCodeLine{  '.ts': typeScriptLoader,}
\DoxyCodeLine{  '.coffee': coffeeScriptLoader}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{// Allow many flavors of JS but rely on require hooks:}
\DoxyCodeLine{\{}
\DoxyCodeLine{  '.mjs': cosmiconfig.loadJs,}
\DoxyCodeLine{  '.ts': cosmiconfig.loadJs,}
\DoxyCodeLine{  '.coffee': cosmiconfig.loadJs}
\DoxyCodeLine{\} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6817}{}\doxysubsection{package\+Prop}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6817}
Type\+: {\ttfamily string $\vert$ Array$<$string$>$}. Default\+: {\ttfamily \`{}\$\{module\+Name\}\`{}}.

Name of the property in {\ttfamily package.\+json} to look for.

Use a period-\/delimited string or an array of strings to describe a path to nested properties.

For example, the value `\textquotesingle{}configs.\+my\+Package'{\ttfamily or}\mbox{[}\textquotesingle{}configs\textquotesingle{}, \textquotesingle{}my\+Package\textquotesingle{}\mbox{]}{\ttfamily will get you the}\char`\"{}my\+Package\char`\"{}{\ttfamily value in a}package.\+json\`{} like this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\{}
\DoxyCodeLine{  "{}configs"{}: \{}
\DoxyCodeLine{    "{}myPackage"{}: \{..\}}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\} }

\end{DoxyCode}


If nested property names within the path include periods, you need to use an array of strings. For example, the value `\mbox{[}\textquotesingle{}configs', \textquotesingle{}foo.\+bar\textquotesingle{}, \textquotesingle{}baz\textquotesingle{}\mbox{]}{\ttfamily will get you the}\char`\"{}baz\char`\"{}{\ttfamily value in a}package.\+json\`{} like this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\{}
\DoxyCodeLine{  "{}configs"{}: \{}
\DoxyCodeLine{    "{}foo.bar"{}: \{}
\DoxyCodeLine{      "{}baz"{}: \{..\}}
\DoxyCodeLine{    \}}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\} }

\end{DoxyCode}


If a string includes period but corresponds to a top-\/level property name, it will not be interpreted as a period-\/delimited path. For example, the value `\textquotesingle{}one.\+two'{\ttfamily will get you the}\char`\"{}three\char`\"{}{\ttfamily value in a}package.\+json\`{} like this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\{}
\DoxyCodeLine{  "{}one.two"{}: "{}three"{},}
\DoxyCodeLine{  "{}one"{}: \{}
\DoxyCodeLine{    "{}two"{}: "{}four"{}}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6818}{}\doxysubsection{stop\+Dir}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6818}
Type\+: {\ttfamily string}. Default\+: Absolute path to your home directory.

Directory where the search will stop.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6819}{}\doxysubsection{cache}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6819}
Type\+: {\ttfamily boolean}. Default\+: {\ttfamily true}.

If {\ttfamily false}, no caches will be used. Read more about \href{\#caching}{\texttt{ \char`\"{}\+Caching\char`\"{}}} below.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6820}{}\doxysubsection{transform}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6820}
Type\+: {\ttfamily (Result) =$>$ Promise$<$Result$>$ $\vert$ Result}.

A function that transforms the parsed configuration. Receives the \href{\#result}{\texttt{ result}}.

If using \href{\#explorersearch}{\texttt{ {\ttfamily search()}}} or \href{\#explorerload}{\texttt{ {\ttfamily load()}}} (which are async), the transform function can return the transformed result or return a Promise that resolves with the transformed result. If using \href{\#explorersearchsync}{\texttt{ {\ttfamily search\+Sync()}}} or \href{\#explorerloadsync}{\texttt{ {\ttfamily load\+Sync()}}}, the function must be synchronous and return the transformed result.

The reason you might use this option —~instead of simply applying your transform function some other way —~is that {\itshape the transformed result will be cached}. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is searched or loaded.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6821}{}\doxysubsection{ignore\+Empty\+Search\+Places}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6821}
Type\+: {\ttfamily boolean}. Default\+: {\ttfamily true}.

By default, if \href{\#explorersearch}{\texttt{ {\ttfamily search()}}} encounters an empty file (containing nothing but whitespace) in one of the \href{\#searchplaces}{\texttt{ {\ttfamily search\+Places}}}, it will ignore the empty file and move on. If you\textquotesingle{}d like to load empty configuration files, instead, set this option to {\ttfamily false}.

Why might you want to load empty configuration files? If you want to throw an error, or if an empty configuration file means something to your program.\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6822}{}\doxysection{Caching}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6822}
As of v2, cosmiconfig uses caching to reduce the need for repetitious reading of the filesystem or expensive transforms. Every new cosmiconfig instance (created with {\ttfamily cosmiconfig()}) has its own caches.

To avoid or work around caching, you can do the following\+:


\begin{DoxyItemize}
\item Set the {\ttfamily cosmiconfig} option \href{\#cache}{\texttt{ {\ttfamily cache}}} to {\ttfamily false}.
\item Use the cache-\/clearing methods \href{\#explorerclearloadcache}{\texttt{ {\ttfamily clear\+Load\+Cache()}}}, \href{\#explorerclearsearchcache}{\texttt{ {\ttfamily clear\+Search\+Cache()}}}, and \href{\#explorerclearcaches}{\texttt{ {\ttfamily clear\+Caches()}}}.
\item Create separate instances of cosmiconfig (separate \char`\"{}explorers\char`\"{}).
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6823}{}\doxysection{Differences from $<$a href=\char`\"{}https\+://github.\+com/dominictarr/rc\char`\"{}$>$rc$<$/a$>$}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6823}
\href{https://github.com/dominictarr/rc}{\texttt{ rc}} serves its focused purpose well. cosmiconfig differs in a few key ways —~making it more useful for some projects, less useful for others\+:


\begin{DoxyItemize}
\item Looks for configuration in some different places\+: in a {\ttfamily package.\+json} property, an rc file, a {\ttfamily .config.\+js} file, and rc files with extensions.
\item Built-\/in support for JSON, YAML, and Common\+JS formats.
\item Stops at the first configuration found, instead of finding all that can be found up the directory tree and merging them automatically.
\item Options.
\item Asynchronous by default (though can be run synchronously).
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6824}{}\doxysection{Contributing \& Development}\label{md_sfcode_node_modules_cosmiconfig_README_autotoc_md6824}
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! 