XDG User Directories

Node.js/TypeScript implementation of the XDG user directories specification.

Installation

npm install xdg-user-dirs

Building from source

git clone https://github.com/loyalpartner/xdg-user-dirs.git
cd xdg-user-dirs
npm install
npm run build

Usage

As a library

import { XDGUserDirectories } from 'xdg-user-dirs';

const xdg = new XDGUserDirectories();

// Get specific directory
console.log(xdg.getDesktop()); // /home/user/Desktop
console.log(xdg.getDownload()); // /home/user/Downloads

// Get all directories
const dirs = xdg.getAll();
dirs.forEach(dir => {
  console.log(`${dir.name}: ${dir.path}`);
});

// Create missing directories
xdg.createDirectories();

As a CLI tool

After installation, the xdg-user-dir command will be available:

# Get specific directory
xdg-user-dir DESKTOP
xdg-user-dir DOWNLOAD

# List all directories
xdg-user-dir --list

# Create all directories
xdg-user-dir --create

Configuration

Main Configuration

The tool reads configuration from ~/.config/user-dirs.dirs file following the XDG specification format:

XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_TEMPLATES_DIR="$HOME/Templates"
XDG_PUBLICSHARE_DIR="$HOME/Public"
XDG_DOCUMENTS_DIR="$HOME/Documents"
XDG_MUSIC_DIR="$HOME/Music"
XDG_PICTURES_DIR="$HOME/Pictures"
XDG_VIDEOS_DIR="$HOME/Videos"

Localized Directories

The tool automatically handles localized directory names in the config file. The system's xdg-user-dirs-update tool manages the locale-specific directory names based on your system locale.

Example Chinese configuration (~/.config/user-dirs.dirs on a Chinese system):

XDG_DESKTOP_DIR="$HOME/桌面"
XDG_DOWNLOAD_DIR="$HOME/下载"
XDG_TEMPLATES_DIR="$HOME/模板"
XDG_PUBLICSHARE_DIR="$HOME/公共"
XDG_DOCUMENTS_DIR="$HOME/文档"
XDG_MUSIC_DIR="$HOME/音乐"
XDG_PICTURES_DIR="$HOME/图片"
XDG_VIDEOS_DIR="$HOME/视频"

Global Defaults

The tool also reads global defaults from /etc/xdg/user-dirs.defaults if available, which are overridden by user-specific configuration.

Testing

npm test
npm run test:coverage