@folder/xdg

中文文档

4.0.1发布于 2023/08/03MITCommonJS近 30 天下载 13.7万

Get cross-platform XDG Base Directories or their equivalents. Works with Linux, Windows (win32), or MacOS (darwin).

文档目录22 节

Install
Usage
Options
Examples
MacOS (darwin)
Linux
Windows (win32)
MacOS (darwin)
Linux
Windows (win32)
Main Export
xdg
.darwin
.linux
.win32
XDG Base Directories
User directories
System directories
About
Related projects
Author
License

@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:

$ npm install --save @folder/xdg

Usage

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.

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.

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' }));

Click to see example with no options

The following examples show what the paths look like when no options are passed.

console.log(xdg());

MacOS (darwin)

{
  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'
}

Linux

{
  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'
}

Windows (win32)

{
  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'
}

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.

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')

MacOS (darwin)

{
  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' }
}

Linux

{
  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' }
}

Windows (win32)

{
  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' }
}

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):

cache
config
configdirs
data
datadirs
runtime

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

const dirs = xdg.darwin();
// or
const 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

const 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

const dirs = xdg.win32();
// or
const 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.
XDG_CACHE_HOME
- Where user-specific non-essential (cached) data should be written (analogous to /var/cache).
- Should default to $HOME/.cache.
XDG_DATA_HOME
- Where user-specific data files should be written (analogous to /usr/share).
- Should default to $HOME/.local/share.
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 to PATH).
- Should default to /usr/local/share:/usr/share.
XDG_CONFIG_DIRS
- List of directories seperated by : (analogous to PATH).
- Should default to /etc/xdg.

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:

$ 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:

$ npm install -g verbose/verb#dev verb-generate-readme && verb

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

This file was generated by verb-generate-readme, v0.8.0, on July 24, 2023.

版本与发布记录

@folder/xdg 共发布 11 个版本，首次发布于 2019/07/03；过去 12 个月发布了 0 个版本。

版本	发布日期	距今
`4.0.1`latest	2023/08/03	3 年前
`4.0.0`	2023/07/25	3 年前
`3.1.2`	2020/07/15	6 年前
`3.1.1`	2020/07/15	6 年前
`3.1.0`	2020/07/14	6 年前
`3.0.0`	2020/07/14	6 年前

关于 @folder/xdg 的常见问题

@folder/xdg 是什么？

Get cross-platform XDG Base Directories or their equivalents. Works with Linux, Windows (win32), or MacOS (darwin).

如何安装 @folder/xdg？

在项目目录运行 npm install @folder/xdg，或使用 pnpm add / yarn add / bun add。

@folder/xdg 支持 TypeScript 吗？

该包的 package.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/folder__xdg 是否存在。

@folder/xdg 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@folder/xdg 可以商用吗？

@folder/xdg 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@folder/xdg 的下载量有多少？

根据 npm 官方下载统计，@folder/xdg 在 2026/10/15 – 2026/11/13 这 30 天内被下载 136,917 次，日均约 4,564 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@folder/xdg 还在维护吗？

最新版本 4.0.1 发布于 2023/08/03（3 年前）；至今共发布 11 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/07/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @folder/xdg

pnpmpnpm add @folder/xdg
yarnyarn add @folder/xdg
bunbun add @folder/xdg

在你的项目目录中运行此命令。

近 30 天下载

136,917

约 13.7万次日均 4,564 次

统计周期 2026/10/15 – 2026/11/13
数据来自 npm 官方下载统计，今天更新

最新版本4.0.1发布于 3 年前

开源许可MIT宽松许可

包体积39.1 kB6 个文件 · 解压后

运行依赖5 个

模块格式CommonJS

TypeScript未声明类型可查找 @types/folder__xdg

发布版本11 个近 12 个月 0 个

首次发布2019/07/037 年前

元数据更新2023/08/03

每一个软件包背后，
都有分享与创造的人。

@folder/xdg

@folder/xdg

Install

Usage

Options

Examples

MacOS (darwin)

Linux

Windows (win32)

MacOS (darwin)

Linux

Windows (win32)

API

Main Export

xdg

.darwin

.linux

.win32

XDG Base Directories

User directories

System directories

About

Related projects

Author

License

版本与发布记录

关于 @folder/xdg 的常见问题

@folder/xdg 是什么？

如何安装 @folder/xdg？

@folder/xdg 支持 TypeScript 吗？

@folder/xdg 支持 ESM 还是 CommonJS？

@folder/xdg 可以商用吗？

@folder/xdg 的下载量有多少？

@folder/xdg 还在维护吗？