Get cross-platform XDG Base Directories or their equivalents. Works with Linux, Windows, or MacOS.
Get cross-platform XDG Base Directories or their equivalents. Works with Linux, Windows (win32), or MacOS (darwin).
Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.
Install with npm:
$ npm install --save @folder/xdg
Add the following line of code to your Node.js application:
const xdg = require('@folder/xdg');
The main export is a function that may be called with an options object:
const dirs = xdg(/* options */);
console.log(dirs);
/* This output is on MacOS, see examples for Linux and Windows below */
console.log(dirs.config); // => '/Users/jonschlinkert/Library/Preferences'
console.log(dirs.cache); // => '/Users/jonschlinkert/Library/Caches'
console.log(dirs.data); // => '/Users/jonschlinkert/Library/Application Support'
See example output by platform.
Option | Type | Description | Default Value |
---|---|---|---|
cachedir |
string |
Override the default cachedir |
Platform specific, see below |
configdir |
string |
Override the default configdir |
|
datadir |
string |
Override the default datadir |
|
env |
object |
The env object to use for getting paths. |
process.env |
expanded |
boolean |
Expand paths into an object. See the Expanded Paths example for more details. | undefined |
homedir |
string |
The user's home directory. | os.homedir() |
platform |
string |
The platform to use: darwin , linux , win32 |
process.platform |
resolve |
function |
Custom function for resolving paths to each directory. The default function attempts to respect casing in the user's existing directories. | undefined |
runtimedir |
string |
Override the default runtimedir |
|
subdir |
string |
A sub-directory to join to the path, typically the name of your application. This path is joined differently on each platform. See examples. | xdg |
tempdir |
string |
The temp directory to use. | os.tmpdir() |
See examples below.
console.log(xdg.darwin());
console.log(xdg.linux());
console.log(xdg.win32());
// or, if you want "expanded" paths (see the "expanded paths" example)
console.log(xdg({ expanded: true, platform: 'darwin' }));
console.log(xdg({ expanded: true, platform: 'linux' }));
console.log(xdg({ expanded: true, platform: 'win32' }));
console.log(xdg());
{
cache: '/Users/jonschlinkert/Library/Caches/xdg',
config: '/Users/jonschlinkert/Library/Preferences/xdg',
configdirs: [ '/Users/jonschlinkert/Library/Preferences/xdg', '/etc/xdg' ],
data: '/Users/jonschlinkert/Library/Application Support/xdg',
datadirs: [
'/Users/jonschlinkert/Library/Application Support/xdg',
'/usr/local/share/',
'/usr/share/'
],
runtime: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/xdg'
}
{
cache: '/Users/jonschlinkert/.cache/xdg',
config: '/Users/jonschlinkert/.config/xdg',
configdirs: [ '/Users/jonschlinkert/.config/xdg', '/etc/xdg' ],
data: '/Users/jonschlinkert/.local/share/xdg',
datadirs: [
'/Users/jonschlinkert/.local/share/xdg',
'/usr/local/share/',
'/usr/share/'
],
runtime: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/xdg'
}
{
cache: '/Users/jonschlinkert/AppData/Local/xdg/Cache',
config: '/Users/jonschlinkert/AppData/Roaming/xdg/Config',
configdirs: [ '/Users/jonschlinkert/AppData/Roaming/xdg/Config' ],
data: '/Users/jonschlinkert/AppData/Local/xdg/Data',
datadirs: [ '/Users/jonschlinkert/AppData/Local/xdg/Data' ],
runtime: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/xdg'
}
console.log(xdg({ expanded: true, subdir: 'FooBar' }));
Extra directories
Note that the expanded
object includes four additional path properties for convenience:
cwd
- set via options.cwd
or process.cwd()
home
- set via options.homedir
or os.homedir()
temp
- set via options.tempdir
or os.tmpdir()
cache.logs
- set at path.join(cachedir, 'logs')
{
cwd: '/Users/jonschlinkert/dev/@folder/xdg',
home: '/Users/jonschlinkert',
temp: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T',
cache: {
home: '/Users/jonschlinkert/Library/Caches/FooBar',
logs: '/Users/jonschlinkert/Library/Caches/FooBar/Logs'
},
config: {
home: '/Users/jonschlinkert/Library/Preferences/FooBar',
dirs: [ '/Users/jonschlinkert/Library/Preferences/FooBar', '/etc/FooBar' ]
},
data: {
home: '/Users/jonschlinkert/Library/Application Support/FooBar',
dirs: [
'/Users/jonschlinkert/Library/Application Support/FooBar',
'/usr/local/share/',
'/usr/share/'
]
},
runtime: { home: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/FooBar' }
}
{
cwd: '/Users/jonschlinkert/dev/@folder/xdg',
home: '/Users/jonschlinkert',
temp: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T',
cache: {
home: '/Users/jonschlinkert/.cache/FooBar',
logs: '/Users/jonschlinkert/.cache/FooBar/Logs'
},
config: {
home: '/Users/jonschlinkert/.config/FooBar',
dirs: [ '/Users/jonschlinkert/.config/FooBar', '/etc/FooBar' ]
},
data: {
home: '/Users/jonschlinkert/.local/share/FooBar',
dirs: [
'/Users/jonschlinkert/.local/share/FooBar',
'/usr/local/share/',
'/usr/share/'
]
},
runtime: { home: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/FooBar' }
}
{
cwd: '/Users/jonschlinkert/dev/@folder/xdg',
home: '/Users/jonschlinkert',
temp: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T',
cache: {
home: '/Users/jonschlinkert/AppData/Local/FooBar/Cache',
logs: '/Users/jonschlinkert/AppData/Local/FooBar/Cache/Logs'
},
config: {
home: '/Users/jonschlinkert/AppData/Roaming/FooBar/Config',
dirs: [ '/Users/jonschlinkert/AppData/Roaming/FooBar/Config' ]
},
data: {
home: '/Users/jonschlinkert/AppData/Local/FooBar/Data',
dirs: [ '/Users/jonschlinkert/AppData/Local/FooBar/Data' ]
},
runtime: { home: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/FooBar' }
}
Aside from the main export, xdg()
, several platform-specific methods are exposed to simplify getting paths for specific platforms. Note that you can accomplish the same thing by passing the platform on the options to the main export, e.g. { platform: 'linux' }
.
The main export, and each method, returns an object with the following properties (see the XDG Base Directories docs below for more details on how each property is set):
cache
config
configdirs
data
datadirs
runtime
Get the XDG Base Directory paths for Linux, or equivalent paths for Windows or MaxOS.
Params
options
{Object}
returns
{Object}: Returns an object of paths for the current platform.Get XDG equivalent paths for MacOS. Used by the main export when process.platform
is darwin
. Aliased as xdg.macos()
.
Params
options
{Object}
returns
{Object}: Returns an object of paths.Example
const dirs = xdg.darwin();
// or
const dirs = xdg.macos();
Get XDG equivalent paths for Linux. Used by the main export when process.platform
is linux
.
returns
{Object}: Returns an object of paths.returns
{Object}: Returns an object of paths.Example
const dirs = xdg.linux();
Get XDG equivalent paths for MacOS. Used by the main export when process.platform
is win32
. Aliased as xdg.windows()
.
Params
options
{Object}
returns
{Object}: Returns an object of paths.Example
const dirs = xdg.win32();
// or
const dirs = xdg.windows();
This documentation is from the Arch Linux XDG Base Directory docs.
XDG_CONFIG_HOME
/etc
).$HOME/.config
.XDG_CACHE_HOME
/var/cache
).$HOME/.cache
.XDG_DATA_HOME
/usr/share
).$HOME/.local/share
.XDG_RUNTIME_DIR
0700
.XDG_DATA_DIRS
:
(analogous to PATH
)./usr/local/share:/usr/share
.XDG_CONFIG_DIRS
:
(analogous to PATH
)./etc/xdg
.Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verb
You might also be interested in these projects:
Jon Schlinkert
Copyright © 2023, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.8.0, on July 24, 2023.