xdg-app-paths

Get (XDG-compatible) application-specific (and cross-platform) paths for storing things like cache, config, data, state, etc

Installation

npm install xdg-app-paths

Usage

// MyApp.js
const paths = require('xdg-app-paths');

paths.cache();
//(nix)=> '/home/rivy/.cache/MyApp.js'
//(win)=> 'C:\\Users\\rivy\\AppData\\Local\\MyApp\\Cache'

paths.config();
//(nix)=> '/home/rivy/.config/MyApp.js'
//(win)=> 'C:\\Users\\rivy\\AppData\\Roaming\\MyApp\\Config'

paths.data();
//(nix)=> '/home/rivy/.local/share/MyApp.js'
//(win)=> 'C:\\Users\\rivy\\AppData\\Roaming\\MyApp\\Data'

API

Initialization

require('xdg-app-paths')( Options? ): XDGAppPaths()

const xdgAppPaths = require('xdg-app-paths');
// or ...
const xdgAppPaths = require('xdg-app-paths')(options);

The object returned by the module constructor is an XDGAppPaths Function object, augmented with attached methods. When called directly (eg, const p = xdgAppPaths(...)), it acts as a constructor, returning a new, and unrelated, XDGAppPaths object.

Options

Options: string => { name: string }

As a shortcut, when supplied as a string, options is interpreted as the Options name property (ie, options = { name: options }).

Options: object

• default = { name: '', suffix: '', isolated: true }

Options.name: string

• default = ''

Name of your application; used to generate the paths. If missing, null, or empty (''), it is generated automatically from the available process information.

Options.suffix: string

• default = ''

Suffix which is appended to the application name when generating the application paths.

Options.isolated: boolean

• default = true

Default isolation flag.

Methods

All returned path strings are simple, platform-compatible, strings and are not guaranteed to exist. The application is responsible for construction of the directories. If needed, make-dir or mkdirp can be used to create the directories.

xdgAppPaths.cache( DirOptions? ): string

Returns the directory for non-essential data files

xdgAppPaths.config( DirOptions? ): string

Returns the directory for config files

xdgAppPaths.data( DirOptions? ): string

Returns the directory for data files

xdgAppPaths.runtime( DirOptions? ): string?

Returns the directory for runtime files; may return undefined

xdgAppPaths.state( DirOptions? ): string

Returns the directory for state files.

xdgAppPaths.configDirs( DirOptions? ): readonly string[]

Returns a priority-sorted list of possible directories for configuration file storage (includes paths.config() as the first entry)

xdgAppPaths.dataDirs( DirOptions? ): readonly string[]

Returns a priority-sorted list of possible directories for data file storage (includes paths.data() as the first entry)

DirOptions

DirOptions: boolean => { isolated: boolean }

As a shortcut, when supplied as a boolean, dirOptions is interpreted as the DirOptions isolated property (ie, dirOptions = { isolated: dirOptions }).

DirOptions: object

• default = { isolated: true }

DirOptions.isolated: boolean

• default = true

Isolation flag; used to override the default isolation mode, when needed.

xdgAppPaths.$name(): string

Application name used for path construction (from supplied or auto-generated information)

xdgAppPaths.$isolated(): boolean

Default isolation mode used by the particular XDGAppPaths instance

Example

// MyApp.js
const locatePath = require('locate-path');
const mkdirp = require('mkdirp');
const path = require('path');

const appPaths = require('xdg-app-paths');
// Extend appPaths with a "log" location function
appPaths.log = function (dirOptions = null) {
  function typeOf(x) {
    // use avoids circumvention of eslint variable tracking for `x`
    return typeof x;
  }

  if (typeOf(dirOptions) === 'boolean') {
    dirOptions = { isolated: dirOptions };
  }

  if (
    typeOf(dirOptions) !== 'object' ||
    dirOptions === null ||
    typeOf(dirOptions.isolated) !== 'boolean'
  ) {
    dirOptions = { isolated: this.$isolated() };
  }

  return path.join(this.state(dirOptions), (dirOptions.isolated ? '' : this.$name() + '-') + 'log');
};

// log file
const logPath = path.join(appPaths.log(), 'debug.txt');
mkdirp.sync(path.dirname(logPath), 0o700);

// config file
// * search for config file within user preferred directories; otherwise, use preferred directory
const possibleConfigPaths = appPaths
  .configDirs()
  .concat(appPaths.configDirs({ isolated: !appPaths.$isolated() }))
  .map((v) => path.join(v, appPaths.$name() + '.json'));
const configPath = locatePath.sync(possibleConfigPaths) || possibleConfigPaths[0];
// debug(logPath, 'configPath="%s"', configPath);
mkdirp.sync(path.dirname(configPath), 0o700);

// cache file
const cacheDir = path.join(appPaths.cache());
// debug(logPath, 'cacheDir="%s"', cacheDir);
mkdirp.sync(cacheDir, 0o700);
const cachePath = {};
cachePath.orders = path.join(cacheDir, 'orders.json');
cachePath.customers = path.join(cacheDir, 'customers.json');
//...

Discussion

The XDG Base Directory Specification defines categories of user information (ie, "cache", "config", "data", ...), defines their standard storage locations, and defines the standard process for user configuration of those locations (using XDG_CACHE_HOME, etc).

Applications supporting the XDG convention are expected to store user-specific files within these locations, either within the common/shared directory (eg, `${xdg.cache()}/filename`) or within a more isolated application-defined subdirectory (eg, `${xdg.config()/dir/filename`; dir usually being the application name).

Windows ("win32") specific notes

Windows has an alternate convention, offering just two standard locations for applications to persist data, either %APPDATA% (for files which may "roam" with the user between hosts) and %LOCALAPPDATA% (for local-machine-only files). All application files are expected to be stored within an application-unique subdirectory in one of those two locations, usually under a directory matching the application name. There is no further popular convention used to segregate the file types (ie, into "cache", "config", ...) in any way similar to the XDG specification.

So, to support basic XDG-like behavior (that is, segregating the information types into type-specific directories), this module supports a new convention for Windows hosts (taken from xdg-portable), placing the specific types of files into subdirectories under either %APPDATA% or %LOCALAPPDATA%, as appropriate for the file type. The default directories used for the windows platform are listed by xdg-portable.

By default, this module returns paths which are isolated, application-specific sub-directories under the respective common/shared base directories. These sub-directories are purely dedicated to use by the application. If, however, the application requires access to the common/shared areas, the isolated: false option may be used during initialization (or as an optional override for specific function calls) to generate and return the common/shared paths. Note, that when using the command/shared directories, care must be taken not use file names which collide with those used by other applications.

Origins

This module was forked from sindresorhus/env-paths in order to add cross-platform portability and support simpler cross-platform applications.

Related

• xdg-portable ... XDG Base Directory paths (cross-platform)
• env-paths ... inspiration for this module

License

MIT © Roy Ivy III, Sindre Sorhus