userdir

A simple utility to get the cross-platform user home directory

Change Log · 简体中文

Installing

# use pnpm
$ pnpm install userdir

# use npm
$ npm install userdir

# use yarn
$ yarn add userdir

Requirements

• Node.js >= 18

Usage

Basic Usage

import userdir from 'userdir'

userdir() // /Users/username

With Options

import { userdir, userdirAsync, clearCache } from 'userdir'

// With path validation
userdir({ validate: true }) // Returns null if path doesn't exist

// Without cache
userdir({ cache: false })

// Async version
await userdirAsync()

// Clear cache
clearCache()

Options

interface UserdirOptions {
  /** Whether to use cache (default: true) */
  cache?: boolean
  /** Custom environment variables (for testing) */
  env?: typeof process.env
  /** Validate if directory exists (default: false) */
  validate?: boolean
}

API

userdir(options?)

Get the user home directory synchronously.

• Returns: string | null - User home directory path, or null if not found

userdirAsync(options?)

Get the user home directory asynchronously.

• Returns: Promise<string | null>

clearCache()

Clear the internal cache.

Default Export

The default export uses os.homedir() when available, falls back to userdir().

Migration from v1.0 to v1.1

Node.js Version

v1.1 requires Node.js >= 18. If you need to support older versions, stay on v1.0.

Import Changes

The default export behavior remains the same. Named exports are now available:

// v1.0
import userdir from 'userdir'

// v1.1 - Same as before
import userdir from 'userdir'

// v1.1 - New named exports
import { userdir, userdirAsync, clearCache } from 'userdir'

New Features

// Path validation (returns null if path doesn't exist)
userdir({ validate: true })

// Disable cache
userdir({ cache: false })

// Async API
await userdirAsync()

// Clear cache manually
clearCache()

Removed Dependencies

v1.1 no longer depends on core-js or js-cool. If your project relied on these being installed transitively, install them directly.

Build Output

v1.0	v1.1
dist/index.mjs	dist/index.js
dist/index.cjs	dist/index.cjs

Support & Issues

Please open an issue here.

License

MIT