or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-xdg-basedir

Get XDG Base Directory paths for user-specific data, config, cache, and runtime files on Linux systems

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/xdg-basedir@5.1.x

To install, run

npx @tessl/cli install tessl/npm-xdg-basedir@5.1.0

index.mddocs/

XDG Base Directory

XDG Base Directory provides access to XDG Base Directory specification paths on Linux systems. It exports constants that resolve XDG environment variables with fallbacks to standard locations, returning directory paths for user-specific data, configuration, cache, state, and runtime files.

Package Information

  • Package Name: xdg-basedir
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install xdg-basedir

Core Imports

import { xdgData, xdgConfig, xdgState, xdgCache, xdgRuntime, xdgDataDirectories, xdgConfigDirectories } from 'xdg-basedir';

Note: This package is ESM-only and requires Node.js to support ES modules. CommonJS require() is not supported.

Basic Usage

import { xdgData, xdgConfig, xdgDataDirectories } from 'xdg-basedir';

console.log(xdgData);
//=> '/home/username/.local/share'

console.log(xdgConfig);
//=> '/home/username/.config'

console.log(xdgDataDirectories);
//=> ['/home/username/.local/share', '/usr/local/share/', '/usr/share/']

// Handle undefined case for single directories
if (xdgData) {
  // Safe to use xdgData directory
  const appDataDir = path.join(xdgData, 'myapp');
} else {
  // Fallback to temporary directory or handle error
  console.error('XDG_DATA_HOME not set and home directory unavailable');
}

Capabilities

User Data Directory

Directory for user-specific data files. Resolves XDG_DATA_HOME environment variable or falls back to ~/.local/share.

const xdgData: string | undefined;

Usage Example:

import { xdgData } from 'xdg-basedir';
import path from 'path';

if (xdgData) {
  const appDataPath = path.join(xdgData, 'myapp', 'data.json');
  // Store application data files
}

User Configuration Directory

Directory for user-specific configuration files. Resolves XDG_CONFIG_HOME environment variable or falls back to ~/.config.

const xdgConfig: string | undefined;

Usage Example:

import { xdgConfig } from 'xdg-basedir';
import path from 'path';

if (xdgConfig) {
  const configPath = path.join(xdgConfig, 'myapp', 'config.json');
  // Store application configuration files
}

User State Directory

Directory for user-specific state files. Resolves XDG_STATE_HOME environment variable or falls back to ~/.local/state.

const xdgState: string | undefined;

Usage Example:

import { xdgState } from 'xdg-basedir';
import path from 'path';

if (xdgState) {
  const statePath = path.join(xdgState, 'myapp', 'session.json');
  // Store application state files like window positions, recently opened files
}

User Cache Directory

Directory for user-specific non-essential data files. Resolves XDG_CACHE_HOME environment variable or falls back to ~/.cache.

const xdgCache: string | undefined;

Usage Example:

import { xdgCache } from 'xdg-basedir';
import path from 'path';

if (xdgCache) {
  const cachePath = path.join(xdgCache, 'myapp');
  // Store temporary files, downloaded assets, compiled code
}

User Runtime Directory

Directory for user-specific non-essential runtime files and other file objects (such as sockets, named pipes, etc). Resolves XDG_RUNTIME_DIR environment variable or returns undefined.

const xdgRuntime: string | undefined;

Usage Example:

import { xdgRuntime } from 'xdg-basedir';
import path from 'path';

if (xdgRuntime) {
  const socketPath = path.join(xdgRuntime, 'myapp.sock');
  // Store runtime files like sockets, named pipes, lock files
}

Data Search Directories

Preference-ordered array of base directories to search for data files in addition to xdgData. Includes xdgData (if defined) plus directories from XDG_DATA_DIRS environment variable or default /usr/local/share/:/usr/share/.

const xdgDataDirectories: readonly string[];

Usage Example:

import { xdgDataDirectories } from 'xdg-basedir';
import path from 'path';
import fs from 'fs';

// Search for a data file across all data directories
function findDataFile(filename) {
  for (const dir of xdgDataDirectories) {
    const filePath = path.join(dir, 'myapp', filename);
    if (fs.existsSync(filePath)) {
      return filePath;
    }
  }
  return null;
}

Configuration Search Directories

Preference-ordered array of base directories to search for configuration files in addition to xdgConfig. Includes xdgConfig (if defined) plus directories from XDG_CONFIG_DIRS environment variable or default /etc/xdg.

const xdgConfigDirectories: readonly string[];

Usage Example:

import { xdgConfigDirectories } from 'xdg-basedir';
import path from 'path';
import fs from 'fs';

// Search for a config file across all config directories
function findConfigFile(filename) {
  for (const dir of xdgConfigDirectories) {
    const filePath = path.join(dir, 'myapp', filename);
    if (fs.existsSync(filePath)) {
      return filePath;
    }
  }
  return null;
}

Platform Requirements

  • Node.js: >= 12
  • Platform: Linux/Unix systems (follows XDG Base Directory specification)
  • Not recommended: macOS or Windows (use env-paths instead for cross-platform support)

Error Handling

All single directory exports (xdgData, xdgConfig, xdgState, xdgCache, xdgRuntime) may return undefined in the uncommon case that both the XDG environment variable is not set and the user's home directory cannot be found. Applications should handle this case by providing fallbacks:

import { xdgData } from 'xdg-basedir';
import path from 'path';
import os from 'os';

// Safe usage with fallback
const dataDir = xdgData || path.join(os.tmpdir(), 'myapp-data');

Array exports (xdgDataDirectories, xdgConfigDirectories) always return non-empty arrays with system defaults even if environment variables are not set.