platform-paths
Retrieve platform specific paths to user folders such as downloads
, documents
, etc.
Supports linux
, darwin
, and win32
platforms.
Available paths: tmp
, home
, downloads
, documents
, pictures
, music
, videos
, desktop
.
Retrieval methods:
- Linux: uses
xdg-user-dir
with a fallback to standard path names. - Windows: uses
reg query
to retrieve and parse out the paths with a fallback to standard path names. - macOS: simply constructs the standard path, as afaik these don't change on mac.
Pros:
- Tiny & simple.
- No dependencies.
- No native modules, bindings, or binaries.
- Built in caching.
Cons:
- Potentially less robust than other alternatives.
Install
npm install platform-paths
Usage
import {getPlatformPath, platformPaths, getDownloadsPath} from 'platform-paths';
const downloadsPath = await getPlatformPath('downloads');
// or
const downloadsPath = await platformPaths.download();
// or
const downloadsPath = await getDownloadsPath();
API
Exported interfaces:
interface Options {
maxAge?: number; // milliseconds, default: 0 (no caching)
}
// Name getter
async function getPlatformPath(name: string, options?: Options): Promise<string>;
// Individual getters
async function getTmpPath(options?: Options): Promise<string>;
async function getHomePath(options?: Options): Promise<string>;
async function getDownloadsPath(options?: Options): Promise<string>;
async function getDocumentsPath(options?: Options): Promise<string>;
async function getPicturesPath(options?: Options): Promise<string>;
async function getMusicPath(options?: Options): Promise<string>;
async function getVideosPath(options?: Options): Promise<string>;
async function getDesktopPath(options?: Options): Promise<string>;
// Individual getters as a map
const platformPaths = {
tmp: (options?: Options) => Promise<string>,
home: (options?: Options) => Promise<string>,
downloads: (options?: Options) => Promise<string>,
documents: (options?: Options) => Promise<string>,
pictures: (options?: Options) => Promise<string>,
music: (options?: Options) => Promise<string>,
videos: (options?: Options) => Promise<string>,
desktop: (options?: Options) => Promise<string>,
};
// Checks if string is a platform path identifier
// (one of platformPaths keys)
function isPlatformPathIdentifier(name: string): name is keyof typeof platformPaths;
// Manual cache clearing
function clearCache(): void;
Caching
The retrieval methods for these paths are not instant, so if you're calling this a lot, you might want to enable caching.
This is done by simply passing a maxAge
option to any of the exported methods. This options is 0
by default (caching disabled):
// Re-queries when older than 10 seconds
const downloadsPath = getPlatformPath('downloads', {maxAge: 10_000});
// Only queries 1st time, then always cached
const downloadsPath = getDownloadsPath({maxAge: Infinity});
License
MIT