platformdirs

platformdirs for JavaScript

📂 Unified interface to get platform-specific directories

Running on Linux const dirs = new PlatformDirs("awesome-app", "octocat", "1.2") console.log(dirs.userDataDir) //=> /home/jcbhmr/.local/share/awesome-app/1.2 console.log(dirs.userConfigDir) //=> /home/jcbhmr/.config/awesome-app/1.2 console.log(userRuntimeDir("other-app", "ferris", "4.5")) //=> /run/user/33333/other-app/4.5 console.log(userLogDir("my-app", "gopher", "7.8")) //=> /home/jcbhmr/.local/state/my-app/7.8/log

Documentation | Original platformdirs project

🚀 Works on Windows, macOS, Linux, and Android^{not yet}
✅ Uses platform-specific best practices
🐍 A re-implementation of Python's platformdirs package

Installation

You can install this package from the npm registry using npm, Yarn, pnpm, Bun, Deno, etc.

npm install platformdirs

Usage

import * as fs from "node:fs/promises";
import * as path from "node:path";
import * as stream from "node:stream";
import * as platformdirs from "platformdirs";

const cacheDir = platformdirs.userCacheDir("awesome-app", "octocat", "1.2")
const bigCSVPath = path.join(cacheDir, "big.csv");
if (!fs.existsSync(bigCSVPath)) {
    const response = await fetch("https://example.com/big.csv");
    await response.body.pipeTo(stream.Writable.toWeb(fs.createWriteStream(bigCSVPath)));
}

📚 For more information check out the documentation

npx platformdirs

Output on Windows

Output on macOS

Output on Linux

-- platformdirs 4.3.6 --
-- app dirs (with optional 'version')
user_data_dir: /home/me/.local/share/MyApp/1.0
user_config_dir: /home/me/.config/MyApp/1.0
user_cache_dir: /home/me/.cache/MyApp/1.0
user_state_dir: /home/me/.local/state/MyApp/1.0
user_log_dir: /home/me/.local/state/MyApp/1.0/log
user_documents_dir: /home/me/Documents
user_downloads_dir: /home/me/Downloads
user_pictures_dir: /home/me/Pictures
user_videos_dir: /home/me/Videos
user_music_dir: /home/me/Music
user_runtime_dir: /run/user/1000/MyApp/1.0
site_data_dir: /usr/local/share/MyApp/1.0
site_config_dir: /etc/xdg/MyApp/1.0
site_cache_dir: /var/cache/MyApp/1.0
site_runtime_dir: /run/MyApp/1.0

-- app dirs (without optional 'version')
user_data_dir: /home/me/.local/share/MyApp
user_config_dir: /home/me/.config/MyApp
user_cache_dir: /home/me/.cache/MyApp
user_state_dir: /home/me/.local/state/MyApp
user_log_dir: /home/me/.local/state/MyApp/log
user_documents_dir: /home/me/Documents
user_downloads_dir: /home/me/Downloads
user_pictures_dir: /home/me/Pictures
user_videos_dir: /home/me/Videos
user_music_dir: /home/me/Music
user_runtime_dir: /run/user/1000/MyApp
site_data_dir: /usr/local/share/MyApp
site_config_dir: /etc/xdg/MyApp
site_cache_dir: /var/cache/MyApp
site_runtime_dir: /run/MyApp

-- app dirs (without optional 'appauthor')
user_data_dir: /home/me/.local/share/MyApp
user_config_dir: /home/me/.config/MyApp
user_cache_dir: /home/me/.cache/MyApp
user_state_dir: /home/me/.local/state/MyApp
user_log_dir: /home/me/.local/state/MyApp/log
user_documents_dir: /home/me/Documents
user_downloads_dir: /home/me/Downloads
user_pictures_dir: /home/me/Pictures
user_videos_dir: /home/me/Videos
user_music_dir: /home/me/Music
user_runtime_dir: /run/user/1000/MyApp
site_data_dir: /usr/local/share/MyApp
site_config_dir: /etc/xdg/MyApp
site_cache_dir: /var/cache/MyApp
site_runtime_dir: /run/MyApp

-- app dirs (with disabled 'appauthor')
user_data_dir: /home/me/.local/share/MyApp
user_config_dir: /home/me/.config/MyApp
user_cache_dir: /home/me/.cache/MyApp
user_state_dir: /home/me/.local/state/MyApp
user_log_dir: /home/me/.local/state/MyApp/log
user_documents_dir: /home/me/Documents
user_downloads_dir: /home/me/Downloads
user_pictures_dir: /home/me/Pictures
user_videos_dir: /home/me/Videos
user_music_dir: /home/me/Music
user_runtime_dir: /run/user/1000/MyApp
site_data_dir: /usr/local/share/MyApp
site_config_dir: /etc/xdg/MyApp
site_cache_dir: /var/cache/MyApp
site_runtime_dir: /run/MyApp

Development

This project uses Node.js, TypeScript, and npm. Why Node.js instead of Deno & JSR? Because it's not as popular (yet). I'd love to use Deno & JSR but nobody knows what they are. This project does use Biome instead of the usual Prettier & ESLint combo. Why? Because ESLint bungled their v9 release and Biome offers a more cohesive linter & formatter solution.