Gathering detailed insights and metrics for @folder/xdg
Gathering detailed insights and metrics for @folder/xdg
Get cross-platform XDG Base Directories or their equivalents. Works with Linux, Windows, or MacOS.
Installations
npm install @folder/xdgDeveloper Guide
BETA
Typescript
No
Module System
CommonJS
Node Version
18.16.1
NPM Version
9.5.1
Score
88.4
Supply Chain
100
Quality
77.5
Maintenance
100
Vulnerability
100
License
Releases
Unable to fetch releases
Languages
1
JavaScript
JavaScript (100%)
Developer
folder
Download Statistics
Total Downloads
247,312
Last Day
32
Last Week
6,735
Last Month
32,218
Last Year
199,364
GitHub Statistics
67 Stars
39 Commits
5 Forks
1 Watchers
1 Branches
4 Contributors
Updated on May 09, 2025
Bundle Size
166.45 kB
Minified
48.66 kB
Minified + Gzipped
Maintainers
2
Package Meta Information
Latest Version
4.0.1
Package Id
@folder/xdg@4.0.1
Unpacked Size
38.19 kB
Size
9.66 kB
File Count
6
NPM Version
9.5.1
Node Version
18.16.1
Published on
Aug 03, 2023
Total Downloads
Cumulative downloads
Total Downloads
247,312
Last Day
-60.5%
32
Compared to previous day
Last Week
-23.7%
6,735
Compared to previous week
Last Month
-11.2%
32,218
Compared to previous month
Last Year
759.1%
199,364
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
@folder/xdg 
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
Install with npm:
1$ npm install --save @folder/xdg
Usage
Add the following line of code to your Node.js application:
1const xdg = require('@folder/xdg');
The main export is a function that may be called with an options object:
1const dirs = xdg(/* options */); 2console.log(dirs); 3 4/* This output is on MacOS, see examples for Linux and Windows below */ 5console.log(dirs.config); // => '/Users/jonschlinkert/Library/Preferences' 6console.log(dirs.cache); // => '/Users/jonschlinkert/Library/Caches' 7console.log(dirs.data); // => '/Users/jonschlinkert/Library/Application Support'
See example output by platform.
Options
Click to see all available options
The following options are available for customizing behavior and/or testing behavior.
| 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.
Examples
Click to see example for platform-specific paths
Get paths for a specific platform.
1console.log(xdg.darwin()); 2console.log(xdg.linux()); 3console.log(xdg.win32()); 4// or, if you want "expanded" paths (see the "expanded paths" example) 5console.log(xdg({ expanded: true, platform: 'darwin' })); 6console.log(xdg({ expanded: true, platform: 'linux' })); 7console.log(xdg({ expanded: true, platform: 'win32' }));
Click to see example with no options
The following examples show what the paths look like when no options are passed.
1console.log(xdg());
MacOS (darwin)
1{ 2 cache: '/Users/jonschlinkert/Library/Caches/xdg', 3 config: '/Users/jonschlinkert/Library/Preferences/xdg', 4 configdirs: [ '/Users/jonschlinkert/Library/Preferences/xdg', '/etc/xdg' ], 5 data: '/Users/jonschlinkert/Library/Application Support/xdg', 6 datadirs: [ 7 '/Users/jonschlinkert/Library/Application Support/xdg', 8 '/usr/local/share/', 9 '/usr/share/' 10 ], 11 runtime: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/xdg' 12}
Linux
1{ 2 cache: '/Users/jonschlinkert/.cache/xdg', 3 config: '/Users/jonschlinkert/.config/xdg', 4 configdirs: [ '/Users/jonschlinkert/.config/xdg', '/etc/xdg' ], 5 data: '/Users/jonschlinkert/.local/share/xdg', 6 datadirs: [ 7 '/Users/jonschlinkert/.local/share/xdg', 8 '/usr/local/share/', 9 '/usr/share/' 10 ], 11 runtime: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/xdg' 12}
Windows (win32)
1{ 2 cache: '/Users/jonschlinkert/AppData/Local/xdg/Cache', 3 config: '/Users/jonschlinkert/AppData/Roaming/xdg/Config', 4 configdirs: [ '/Users/jonschlinkert/AppData/Roaming/xdg/Config' ], 5 data: '/Users/jonschlinkert/AppData/Local/xdg/Data', 6 datadirs: [ '/Users/jonschlinkert/AppData/Local/xdg/Data' ], 7 runtime: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/xdg' 8}
Click to see "expanded" paths example
Running the following example returns an object with "expanded" paths, where `config` and `configdirs` are converted to `config.home` and `config.dirs`, etc. Additionally, `cwd`, `home` and `temp` paths are added for convenience.
1console.log(xdg({ expanded: true, subdir: 'FooBar' }));
Extra directories
Note that the expanded object includes four additional path properties for convenience:
cwd- set viaoptions.cwdorprocess.cwd()home- set viaoptions.homediroros.homedir()temp- set viaoptions.tempdiroros.tmpdir()cache.logs- set atpath.join(cachedir, 'logs')
MacOS (darwin)
1{ 2 cwd: '/Users/jonschlinkert/dev/@folder/xdg', 3 home: '/Users/jonschlinkert', 4 temp: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T', 5 cache: { 6 home: '/Users/jonschlinkert/Library/Caches/FooBar', 7 logs: '/Users/jonschlinkert/Library/Caches/FooBar/Logs' 8 }, 9 config: { 10 home: '/Users/jonschlinkert/Library/Preferences/FooBar', 11 dirs: [ '/Users/jonschlinkert/Library/Preferences/FooBar', '/etc/FooBar' ] 12 }, 13 data: { 14 home: '/Users/jonschlinkert/Library/Application Support/FooBar', 15 dirs: [ 16 '/Users/jonschlinkert/Library/Application Support/FooBar', 17 '/usr/local/share/', 18 '/usr/share/' 19 ] 20 }, 21 runtime: { home: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/FooBar' } 22}
Linux
1{ 2 cwd: '/Users/jonschlinkert/dev/@folder/xdg', 3 home: '/Users/jonschlinkert', 4 temp: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T', 5 cache: { 6 home: '/Users/jonschlinkert/.cache/FooBar', 7 logs: '/Users/jonschlinkert/.cache/FooBar/Logs' 8 }, 9 config: { 10 home: '/Users/jonschlinkert/.config/FooBar', 11 dirs: [ '/Users/jonschlinkert/.config/FooBar', '/etc/FooBar' ] 12 }, 13 data: { 14 home: '/Users/jonschlinkert/.local/share/FooBar', 15 dirs: [ 16 '/Users/jonschlinkert/.local/share/FooBar', 17 '/usr/local/share/', 18 '/usr/share/' 19 ] 20 }, 21 runtime: { home: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/FooBar' } 22}
Windows (win32)
1{ 2 cwd: '/Users/jonschlinkert/dev/@folder/xdg', 3 home: '/Users/jonschlinkert', 4 temp: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T', 5 cache: { 6 home: '/Users/jonschlinkert/AppData/Local/FooBar/Cache', 7 logs: '/Users/jonschlinkert/AppData/Local/FooBar/Cache/Logs' 8 }, 9 config: { 10 home: '/Users/jonschlinkert/AppData/Roaming/FooBar/Config', 11 dirs: [ '/Users/jonschlinkert/AppData/Roaming/FooBar/Config' ] 12 }, 13 data: { 14 home: '/Users/jonschlinkert/AppData/Local/FooBar/Data', 15 dirs: [ '/Users/jonschlinkert/AppData/Local/FooBar/Data' ] 16 }, 17 runtime: { home: '/var/folders/vd/53h736bj0_sg9gk04c89k0pr0000gq/T/FooBar' } 18}
API
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):
cacheconfigconfigdirsdatadatadirsruntime
Main Export
xdg
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.
.darwin
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
1const dirs = xdg.darwin(); 2// or 3const dirs = xdg.macos();
.linux
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
1const dirs = xdg.linux();
.win32
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
1const dirs = xdg.win32(); 2// or 3const dirs = xdg.windows();
XDG Base Directories
This documentation is from the Arch Linux XDG Base Directory docs.
User directories
-
XDG_CONFIG_HOME- Where user-specific configurations should be written (analogous to
/etc). - Should default to
$HOME/.config.
- Where user-specific configurations should be written (analogous to
-
XDG_CACHE_HOME- Where user-specific non-essential (cached) data should be written (analogous to
/var/cache). - Should default to
$HOME/.cache.
- Where user-specific non-essential (cached) data should be written (analogous to
-
XDG_DATA_HOME- Where user-specific data files should be written (analogous to
/usr/share). - Should default to
$HOME/.local/share.
- Where user-specific data files should be written (analogous to
-
XDG_RUNTIME_DIR- Used for non-essential, user-specific data files such as sockets, named pipes, etc.
- Not required to have a default value; warnings should be issued if not set or equivalents provided.
- Must be owned by the user with an access mode of
0700. - Filesystem fully featured by standards of OS.
- Must be on the local filesystem.
- May be subject to periodic cleanup.
- Modified every 6 hours or set sticky bit if persistence is desired.
- Can only exist for the duration of the user's login.
- Should not store large files as it may be mounted as a tmpfs.
System directories
-
XDG_DATA_DIRS- List of directories seperated by
:(analogous toPATH). - Should default to
/usr/local/share:/usr/share.
- List of directories seperated by
-
XDG_CONFIG_DIRS- List of directories seperated by
:(analogous toPATH). - Should default to
/etc/xdg.
- List of directories seperated by
About
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running Tests
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:
1$ npm install && npm test
Building docs
(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:
1$ npm install -g verbose/verb#dev verb-generate-readme && verb
Related projects
You might also be interested in these projects:
- expand-tilde: Bash-like tilde expansion for node.js. Expands a leading tilde in a file path to the… more | homepage
- global-modules: The directory used by npm for globally installed npm modules. | homepage
- global-paths: Returns an array of unique "global" directories based on the user's platform and environment. The… more | [homepage](https://github.com/jonschlinkert/global-paths "Returns an array of unique "global" directories based on the user's platform and environment. The resulting paths can be used for doing lookups for generators or other globally installed npm packages. Node.js / JavaScript.")
- normalize-path: Normalize slashes in a file path to be posix/unix-like forward slashes. Also condenses repeat slashes… more | homepage
Author
Jon Schlinkert
License
Copyright © 2023, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.8.0, on July 24, 2023.
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
0 existing vulnerabilities detected
Reason
Found 2/28 approved changesets -- score normalized to 0
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
license file not detected
Details
- Warn: project does not have a license file
Reason
branch protection not enabled on development/release branches
Details
- Warn: branch protection not enabled for branch 'master'
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 4 are checked with a SAST tool
Score
2.6
/10
Last Scanned on 2025-06-23
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More