dis-platform-dirs

!platform-dirs

Dependency-free, cross-platform user directory resolver for Node.js and Bun.
Inspired by Python’s platformdirs.

Install

``bash
bun add dis-platform-dirs


or


npm install dis-platform-dirs
`

Overview

This module provides consistent paths for storing user-specific application data, config files, cache, logs, and runtime data across Linux, macOS, and Windows. All logic is based on environment variables and standard platform conventions.

$3

`ts
import platformDirs from "dis-platform-dirs";
import type { WindowsDirs } from "dis-platform-dirs";

const {
userLogDir,
runtimeDir,
userDataDir,
userCacheDir,
userConfigDir,
userDesktopDir,
userDocumentsDir,
userDownloadsDir,
userMusicDir,
userPicturesDir,
userVideosDir,
siteConfigDir,
siteDataDir,
} = platformDirs as WindowsDirs;

const appName = "SuperApp";
const author = "SuperApp Inc";

console.log({
appName,
runtimeDir: runtimeDir(),
userConfigDir: userConfigDir(appName),
userConfigDirWAuthor: userConfigDir(appName, author),
userConfigDirRoaming: userConfigDir(appName, undefined, true),
userConfigDirRoamingWAuthor: userConfigDir(appName, author, true),
userDataDir: userDataDir(appName),
userDataDirWAuthor: userDataDir(appName, author),
userDataDirRoaming: userDataDir(appName, undefined, true),
userDataDirRoamingWAuthor: userDataDir(appName, author, true),
userCacheDir: userCacheDir(appName),
userCacheDirWAuthor: userCacheDir(appName, author),
userCacheDirRoaming: userCacheDir(appName, undefined, true),
userCacheDirRoamingWAuthor: userCacheDir(appName, author, true),
userLogDir: userLogDir(appName),
userLogDirWAuthor: userLogDir(appName, author),
userLogDirRoaming: userLogDir(appName, undefined, true),
userLogDirRoamingWAuthor: userLogDir(appName, author, true),
siteDataDir: siteDataDir(appName),
siteDataDirWAuthor: siteDataDir(appName, author),
siteConfigDir: siteConfigDir(appName),
siteConfigDirWAuthor: siteConfigDir(appName, author),
userDesktopDir: userDesktopDir(),
userDownloadsDir: userDownloadsDir(),
userDocumentsDir: userDocumentsDir(),
userPicturesDir: userPicturesDir(),
userMusicDir: userMusicDir(),
userVideosDir: userVideosDir(),
});

/*
// Expected output on Windows where is replaced with the current user
{
appName: "SuperApp",
runtimeDir: null,
userConfigDir: "C:\\Users\\\\AppData\\Local\\SuperApp",
userConfigDirWAuthor: "C:\\Users\\\\AppData\\Local\\SuperApp Inc\\SuperApp",
userConfigDirRoaming: "C:\\Users\\\\AppData\\Roaming\\SuperApp",
userConfigDirRoamingWAuthor: "C:\\Users\\\\AppData\\Roaming\\SuperApp Inc\\SuperApp",
userDataDir: "C:\\Users\\\\AppData\\Local\\SuperApp",
userDataDirWAuthor: "C:\\Users\\\\AppData\\Local\\SuperApp Inc\\SuperApp",
userDataDirRoaming: "C:\\Users\\\\AppData\\Roaming\\SuperApp",
userDataDirRoamingWAuthor: "C:\\Users\\\\AppData\\Roaming\\SuperApp Inc\\SuperApp",
userCacheDir: "C:\\Users\\\\AppData\\Local\\SuperApp\\Cache",
userCacheDirWAuthor: "C:\\Users\\\\AppData\\Local\\SuperApp Inc\\SuperApp\\Cache",
userCacheDirRoaming: "C:\\Users\\\\AppData\\Roaming\\SuperApp\\Cache",
userCacheDirRoamingWAuthor: "C:\\Users\\\\AppData\\Roaming\\SuperApp Inc\\SuperApp\\Cache",
userLogDir: "C:\\Users\\\\AppData\\Local\\SuperApp\\Cache\\Logs",
userLogDirWAuthor: "C:\\Users\\\\AppData\\Local\\SuperApp Inc\\SuperApp\\Cache\\Logs",
userLogDirRoaming: "C:\\Users\\\\AppData\\Roaming\\SuperApp\\Cache\\Logs",
userLogDirRoamingWAuthor: "C:\\Users\\\\AppData\\Roaming\\SuperApp Inc\\SuperApp\\Cache\\Logs",
siteDataDir: [ "C:\\ProgramData\\SuperApp" ],
siteDataDirWAuthor: [ "C:\\ProgramData\\SuperApp Inc\\SuperApp" ],
siteConfigDir: [ "C:\\ProgramData\\SuperApp" ],
siteConfigDirWAuthor: [ "C:\\ProgramData\\SuperApp Inc\\SuperApp" ],
userDesktopDir: "C:\\Users\\\\Desktop",
userDownloadsDir: "C:\\Users\\\\Downloads",
userDocumentsDir: "C:\\Users\\\\Documents",
userPicturesDir: "C:\\Users\\\\Pictures",
userMusicDir: "C:\\Users\\\\Music",
userVideosDir: "C:\\Users\\\\Videos",
}
*/
`

$3

`ts
import platformDirs from "dis-platform-dirs";
import type { DarwinDirs } from "dis-platform-dirs";

const {
userLogDir,
runtimeDir,
userDataDir,
userCacheDir,
userConfigDir,
userDesktopDir,
userDocumentsDir,
userDownloadsDir,
userMusicDir,
userPicturesDir,
userVideosDir,
siteConfigDir,
siteDataDir,
} = platformDirs as DarwinDirs;

const appName = "SuperApp";

console.log({
appName,
runtimeDir: runtimeDir(),
userConfigDir: userConfigDir(appName),
userDataDir: userDataDir(appName),
userCacheDir: userCacheDir(appName),
userLogDir: userLogDir(appName),
siteDataDir: siteDataDir(appName),
siteConfigDir: siteConfigDir(appName),
userDesktopDir: userDesktopDir(),
userDownloadsDir: userDownloadsDir(),
userDocumentsDir: userDocumentsDir(),
userPicturesDir: userPicturesDir(),
userMusicDir: userMusicDir(),
userVideosDir: userVideosDir(),
});
/*
// Expected output on macOS where is replaced with the current user
{
appName: "SuperApp",
runtimeDir: null,
userConfigDir: "/Users//Library/Preferences/SuperApp",
userDataDir: "/Users//Library/Application Support/SuperApp",
userCacheDir: "/Users//Library/Caches/SuperApp",
userLogDir: "/Users//Library/Logs/SuperApp",
siteDataDir: [ "/Library/Application Support/SuperApp" ],
siteConfigDir: [ "/Library/Preferences/SuperApp" ],
userDesktopDir: "/Users//Desktop",
userDownloadsDir: "/Users//Downloads",
userDocumentsDir: "/Users//Documents",
userPicturesDir: "/Users//Pictures",
userMusicDir: "/Users//Music",
userVideosDir: "/Users//Movies",
}
*/
`

$3

`ts
import platformDirs from "dis-platform-dirs";
import type { LinuxDirs } from "dis-platform-dirs";

const {
userLogDir,
runtimeDir,
userDataDir,
userCacheDir,
userConfigDir,
userDesktopDir,
userDocumentsDir,
userDownloadsDir,
userMusicDir,
userPicturesDir,
userVideosDir,
siteConfigDir,
siteDataDir,
} = platformDirs as LinuxDirs;

const appName = "SuperApp";

console.log({
appName,
runtimeDir: runtimeDir(appName),
userConfigDir: userConfigDir(appName),
userDataDir: userDataDir(appName),
userCacheDir: userCacheDir(appName),
userLogDir: userLogDir(appName),
siteDataDir: siteDataDir(appName),
siteConfigDir: siteConfigDir(appName),
userDesktopDir: userDesktopDir(),
userDownloadsDir: userDownloadsDir(),
userDocumentsDir: userDocumentsDir(),
userPicturesDir: userPicturesDir(),
userMusicDir: userMusicDir(),
userVideosDir: userVideosDir(),
});

/*
// Expected output on Linux where is replaced with the current user
{
appName: "SuperApp",
runtimeDir: "/run/user/1000/SuperApp", // 1000 is an example id
userConfigDir: "/home//.config/SuperApp",
userDataDir: "/home//.local/share/SuperApp",
userCacheDir: "/home//.cache/SuperApp",
userLogDir: "/home//.local/state/SuperApp/logs",
siteDataDir: [ "/usr/local/share/SuperApp", "/usr/share/SuperApp" ],
siteConfigDir: [ "/etc/xdg/SuperApp" ],
userDesktopDir: "/home//Desktop",
userDownloadsDir: "/home//Downloads",
userDocumentsDir: "/home//Documents",
userPicturesDir: "/home//Pictures",
userMusicDir: "/home//Music",
userVideosDir: "/home//Videos",
}
*/
`

Contributing

Contributions are welcome! To contribute:

1. Fork the repository and.
2. Install any dependencies

`bash
bun install

#npm
npm i
`

3. Create a new branch:

`bash
git checkout -b feature/my-feature
`

4. Develop your changes, using vitest and follow the platform-specific test structure.

5. Run tests:

`bash
bun run test
`

---

To test for a specific platform, i.e. darwin, win32, or linux, use the included scripts:

`bash
#darwin
bun run test:darwin

#win32
bun run test:win32

#linux
bun run test:linux
`

> Note: If using npm, simply replace bun with npm

6. Ensure 100% coverage:

`bash
bun run coverage

#npm
npm run coverage
`

7. Submit a pull request with a clear description and include coverage report, i.e.

`bash
% Coverage report from v8
-------------------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------------|---------|----------|---------|---------|-------------------
All files | 100 | 100 | 100 | 100 |
src | 100 | 100 | 100 | 100 |
index.ts | 100 | 100 | 100 | 100 |
platform.ts | 100 | 100 | 100 | 100 |
xdg-user-dirs.ts | 100 | 100 | 100 | 100 |
src/platforms | 100 | 100 | 100 | 100 |
darwin.ts | 100 | 100 | 100 | 100 |
linux.ts | 100 | 100 | 100 | 100 |
win32.ts | 100 | 100 | 100 | 100 |
-------------------|---------|----------|---------|---------|-------------------
``

> Note: All contributions must comply with the MIT License and cannot contain any runtime dependencies.

License

MIT License

© 2025 Defend I.T. Solutions LLC