0
# XDG Base Directory
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: xdg-basedir
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install xdg-basedir`
10

11
## Core Imports
12

13
```javascript
14
import { xdgData, xdgConfig, xdgState, xdgCache, xdgRuntime, xdgDataDirectories, xdgConfigDirectories } from 'xdg-basedir';
15
```
16

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

19
## Basic Usage
20

21
```javascript
22
import { xdgData, xdgConfig, xdgDataDirectories } from 'xdg-basedir';
23

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

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

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

33
// Handle undefined case for single directories
34
if (xdgData) {
35
  // Safe to use xdgData directory
36
  const appDataDir = path.join(xdgData, 'myapp');
37
} else {
38
  // Fallback to temporary directory or handle error
39
  console.error('XDG_DATA_HOME not set and home directory unavailable');
40
}
41
```
42

43
## Capabilities
44

45
### User Data Directory
46

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

49
```javascript { .api }
50
const xdgData: string | undefined;
51
```
52

53
**Usage Example:**
54

55
```javascript
56
import { xdgData } from 'xdg-basedir';
57
import path from 'path';
58

59
if (xdgData) {
60
  const appDataPath = path.join(xdgData, 'myapp', 'data.json');
61
  // Store application data files
62
}
63
```
64

65
### User Configuration Directory
66

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

69
```javascript { .api }
70
const xdgConfig: string | undefined;
71
```
72

73
**Usage Example:**
74

75
```javascript
76
import { xdgConfig } from 'xdg-basedir';
77
import path from 'path';
78

79
if (xdgConfig) {
80
  const configPath = path.join(xdgConfig, 'myapp', 'config.json');
81
  // Store application configuration files
82
}
83
```
84

85
### User State Directory
86

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

89
```javascript { .api }
90
const xdgState: string | undefined;
91
```
92

93
**Usage Example:**
94

95
```javascript
96
import { xdgState } from 'xdg-basedir';
97
import path from 'path';
98

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

105
### User Cache Directory
106

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

109
```javascript { .api }
110
const xdgCache: string | undefined;
111
```
112

113
**Usage Example:**
114

115
```javascript
116
import { xdgCache } from 'xdg-basedir';
117
import path from 'path';
118

119
if (xdgCache) {
120
  const cachePath = path.join(xdgCache, 'myapp');
121
  // Store temporary files, downloaded assets, compiled code
122
}
123
```
124

125
### User Runtime Directory
126

127
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.
128

129
```javascript { .api }
130
const xdgRuntime: string | undefined;
131
```
132

133
**Usage Example:**
134

135
```javascript
136
import { xdgRuntime } from 'xdg-basedir';
137
import path from 'path';
138

139
if (xdgRuntime) {
140
  const socketPath = path.join(xdgRuntime, 'myapp.sock');
141
  // Store runtime files like sockets, named pipes, lock files
142
}
143
```
144

145
### Data Search Directories
146

147
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/`.
148

149
```javascript { .api }
150
const xdgDataDirectories: readonly string[];
151
```
152

153
**Usage Example:**
154

155
```javascript
156
import { xdgDataDirectories } from 'xdg-basedir';
157
import path from 'path';
158
import fs from 'fs';
159

160
// Search for a data file across all data directories
161
function findDataFile(filename) {
162
  for (const dir of xdgDataDirectories) {
163
    const filePath = path.join(dir, 'myapp', filename);
164
    if (fs.existsSync(filePath)) {
165
      return filePath;
166
    }
167
  }
168
  return null;
169
}
170
```
171

172
### Configuration Search Directories
173

174
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`.
175

176
```javascript { .api }
177
const xdgConfigDirectories: readonly string[];
178
```
179

180
**Usage Example:**
181

182
```javascript
183
import { xdgConfigDirectories } from 'xdg-basedir';
184
import path from 'path';
185
import fs from 'fs';
186

187
// Search for a config file across all config directories
188
function findConfigFile(filename) {
189
  for (const dir of xdgConfigDirectories) {
190
    const filePath = path.join(dir, 'myapp', filename);
191
    if (fs.existsSync(filePath)) {
192
      return filePath;
193
    }
194
  }
195
  return null;
196
}
197
```
198

199
## Platform Requirements
200

201
- **Node.js**: >= 12
202
- **Platform**: Linux/Unix systems (follows XDG Base Directory specification)
203
- **Not recommended**: macOS or Windows (use [`env-paths`](https://github.com/sindresorhus/env-paths) instead for cross-platform support)
204

205
## Error Handling
206

207
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:
208

209
```javascript
210
import { xdgData } from 'xdg-basedir';
211
import path from 'path';
212
import os from 'os';
213

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

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