https://github.com/jcbhmr/platformdirs.js
📂 Unified interface to get platform-specific directories
https://github.com/jcbhmr/platformdirs.js
appdirs bun deno known-folders nodejs platformdirs port xdg xdg-basedir
Last synced: 3 months ago
JSON representation
📂 Unified interface to get platform-specific directories
- Host: GitHub
- URL: https://github.com/jcbhmr/platformdirs.js
- Owner: jcbhmr
- License: mit
- Created: 2024-11-07T02:13:16.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2024-12-28T05:32:45.000Z (7 months ago)
- Last Synced: 2025-03-27T17:51:45.487Z (4 months ago)
- Topics: appdirs, bun, deno, known-folders, nodejs, platformdirs, port, xdg, xdg-basedir
- Language: TypeScript
- Homepage: https://tsdocs.dev/docs/platformdirs
- Size: 133 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `platformdirs` for JavaScript
📂 Unified interface to get platform-specific directories
```js
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`](https://pypi.org/project/platformdirs/) package
## Installation
You can install this package from [the npm registry](https://www.npmjs.com/) using npm, Yarn, pnpm, Bun, Deno, etc.
```sh
npm install platformdirs
```
This package works with Node.js, Deno, and Bun. It is not intended to be used in the browser.
## Usage
```js
import * as fs from "node:fs/promises";
import * as path from "node:path";
import * as stream from "node:stream";
import { userCacheDir } from "platformdirs";
const cacheDir = 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](https://tsdocs.dev/docs/platformdirs)
You can quickly dump all the directories for the current environment by running the included `platformdirs` CLI command. This is helpful for quickly determining what `dirs.userConfigDir` and friends return.
```sh
npx platformdirs
```
Output on Windows
```
-- platformdirs 4.3.7 --
-- app dirs (with optional 'version')
user_data_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\1.0
user_config_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\1.0
user_cache_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\Cache\1.0
user_state_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\1.0
user_log_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\1.0\Logs
user_documents_dir: C:\Users\me\Documents
user_downloads_dir: C:\Users\me\Downloads
user_pictures_dir: C:\Users\me\Pictures
user_videos_dir: C:\Users\me\Videos
user_music_dir: C:\Users\me\Music
user_runtime_dir: C:\Users\me\AppData\Local\Temp\MyCompany\MyApp\1.0
site_data_dir: C:\ProgramData\MyCompany\MyApp\1.0
site_config_dir: C:\ProgramData\MyCompany\MyApp\1.0
site_cache_dir: C:\ProgramData\MyCompany\MyApp\Cache\1.0
site_runtime_dir: C:\Users\me\AppData\Local\Temp\MyCompany\MyApp\1.0
-- app dirs (without optional 'version')
user_data_dir: C:\Users\me\AppData\Local\MyCompany\MyApp
user_config_dir: C:\Users\me\AppData\Local\MyCompany\MyApp
user_cache_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\Cache
user_state_dir: C:\Users\me\AppData\Local\MyCompany\MyApp
user_log_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\Logs
user_documents_dir: C:\Users\me\Documents
user_downloads_dir: C:\Users\me\Downloads
user_pictures_dir: C:\Users\me\Pictures
user_videos_dir: C:\Users\me\Videos
user_music_dir: C:\Users\me\Music
user_runtime_dir: C:\Users\me\AppData\Local\Temp\MyCompany\MyApp
site_data_dir: C:\ProgramData\MyCompany\MyApp
site_config_dir: C:\ProgramData\MyCompany\MyApp
site_cache_dir: C:\ProgramData\MyCompany\MyApp\Cache
site_runtime_dir: C:\Users\me\AppData\Local\Temp\MyCompany\MyApp
-- app dirs (without optional 'appauthor')
user_data_dir: C:\Users\me\AppData\Local\MyApp\MyApp
user_config_dir: C:\Users\me\AppData\Local\MyApp\MyApp
user_cache_dir: C:\Users\me\AppData\Local\MyApp\MyApp\Cache
user_state_dir: C:\Users\me\AppData\Local\MyApp\MyApp
user_log_dir: C:\Users\me\AppData\Local\MyApp\MyApp\Logs
user_documents_dir: C:\Users\me\Documents
user_downloads_dir: C:\Users\me\Downloads
user_pictures_dir: C:\Users\me\Pictures
user_videos_dir: C:\Users\me\Videos
user_music_dir: C:\Users\me\Music
user_runtime_dir: C:\Users\me\AppData\Local\Temp\MyApp\MyApp
site_data_dir: C:\ProgramData\MyApp\MyApp
site_config_dir: C:\ProgramData\MyApp\MyApp
site_cache_dir: C:\ProgramData\MyApp\MyApp\Cache
site_runtime_dir: C:\Users\me\AppData\Local\Temp\MyApp\MyApp
-- app dirs (with disabled 'appauthor')
user_data_dir: C:\Users\me\AppData\Local\MyApp
user_config_dir: C:\Users\me\AppData\Local\MyApp
user_cache_dir: C:\Users\me\AppData\Local\MyApp\Cache
user_state_dir: C:\Users\me\AppData\Local\MyApp
user_log_dir: C:\Users\me\AppData\Local\MyApp\Logs
user_documents_dir: C:\Users\me\Documents
user_downloads_dir: C:\Users\me\Downloads
user_pictures_dir: C:\Users\me\Pictures
user_videos_dir: C:\Users\me\Videos
user_music_dir: C:\Users\me\Music
user_runtime_dir: C:\Users\me\AppData\Local\Temp\MyApp
site_data_dir: C:\ProgramData\MyApp
site_config_dir: C:\ProgramData\MyApp
site_cache_dir: C:\ProgramData\MyApp\Cache
site_runtime_dir: C:\Users\me\AppData\Local\Temp\MyApp
```
Output on macOS
```
TODO
```
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, npm, TypeScript, and [Biome](https://biomejs.dev/) instead of the usual [Prettier](https://prettier.io/) & [ESLint](https://eslint.org/) combo. Why? Because ESLint bungled their v9 release and Biome offers a more cohesive linter & formatter solution.
For package releases make sure to always release a `-rc1` version first. If it's 100% OK then proceed to release it as normal. The goal is to keep the npm `[email protected]` package in sync with PyPI `platformdirs==X.Y.Z`.
So far I have failed at this and now I'm two patch versions _ahead_ of the Python package. Oopsies.