Zero-dependency Bun/Node.js implementation of Python's platformdirs for determining platform-specific user directories.
npm install dis-platform-dirsDependency-free, cross-platform user directory resolver for Node.js and Bun.
Inspired by Python’s platformdirs.
``bash`
bun add dis-platform-dirsor
npm install dis-platform-dirs
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.
`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
{
appName: "SuperApp",
runtimeDir: null,
userConfigDir: "C:\\Users\\
userConfigDirWAuthor: "C:\\Users\\
userConfigDirRoaming: "C:\\Users\\
userConfigDirRoamingWAuthor: "C:\\Users\\
userDataDir: "C:\\Users\\
userDataDirWAuthor: "C:\\Users\\
userDataDirRoaming: "C:\\Users\\
userDataDirRoamingWAuthor: "C:\\Users\\
userCacheDir: "C:\\Users\\
userCacheDirWAuthor: "C:\\Users\\
userCacheDirRoaming: "C:\\Users\\
userCacheDirRoamingWAuthor: "C:\\Users\\
userLogDir: "C:\\Users\\
userLogDirWAuthor: "C:\\Users\\
userLogDirRoaming: "C:\\Users\\
userLogDirRoamingWAuthor: "C:\\Users\\
siteDataDir: [ "C:\\ProgramData\\SuperApp" ],
siteDataDirWAuthor: [ "C:\\ProgramData\\SuperApp Inc\\SuperApp" ],
siteConfigDir: [ "C:\\ProgramData\\SuperApp" ],
siteConfigDirWAuthor: [ "C:\\ProgramData\\SuperApp Inc\\SuperApp" ],
userDesktopDir: "C:\\Users\\
userDownloadsDir: "C:\\Users\\
userDocumentsDir: "C:\\Users\\
userPicturesDir: "C:\\Users\\
userMusicDir: "C:\\Users\\
userVideosDir: "C:\\Users\\
}
*/
`
`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
{
appName: "SuperApp",
runtimeDir: null,
userConfigDir: "/Users/
userDataDir: "/Users/
userCacheDir: "/Users/
userLogDir: "/Users/
siteDataDir: [ "/Library/Application Support/SuperApp" ],
siteConfigDir: [ "/Library/Preferences/SuperApp" ],
userDesktopDir: "/Users/
userDownloadsDir: "/Users/
userDocumentsDir: "/Users/
userPicturesDir: "/Users/
userMusicDir: "/Users/
userVideosDir: "/Users/
}
*/
`
`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
{
appName: "SuperApp",
runtimeDir: "/run/user/1000/SuperApp", // 1000 is an example id
userConfigDir: "/home/
userDataDir: "/home/
userCacheDir: "/home/
userLogDir: "/home/
siteDataDir: [ "/usr/local/share/SuperApp", "/usr/share/SuperApp" ],
siteConfigDir: [ "/etc/xdg/SuperApp" ],
userDesktopDir: "/home/
userDownloadsDir: "/home/
userDocumentsDir: "/home/
userPicturesDir: "/home/
userMusicDir: "/home/
userVideosDir: "/home/
}
*/
`
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.
© 2025 Defend I.T. Solutions LLC