is-empty-dir

A fast utility to check whether one or more directories are empty (optionally ignoring files), with Promise/callback + sync APIs and bundled TypeScript types.

Features

• Fast: Early exit optimization for large directories
• Flexible: Ignore files by name, RegExp, or custom function
• Sync & Async: Use in callback, promise-based, or synchronous code
• Cross-platform: Works on Linux, macOS, and Windows
• Supports CommonJS and ES Modules
• TypeScript-ready: Bundled .d.ts declarations included

Installation

npm install is-empty-dir

Usage

CommonJS

constisEmptyDir=require('is-empty-dir');(async()=>{constempty=awaitisEmptyDir('/path/to/dir');console.log(empty);// true or false})();// Callback styleisEmptyDir('/path/to/dir',(err,empty)=>{if(err){console.error(err);return;}console.log(empty);// true or false});// Synchronousconst{ isEmptyDirSync }=require('is-empty-dir');constemptySync=isEmptyDirSync('/path/to/dir');console.log(emptySync);// true or false

ES Modules

importisEmptyDir,{isEmptyDirSync}from'is-empty-dir';constempty=awaitisEmptyDir('/path/to/dir');constemptySync=isEmptyDirSync('/path/to/dir');

Check multiple directories in one call

constallEmpty=awaitisEmptyDir(['/dir-a','/dir-b']);constallEmptySync=isEmptyDirSync(['/dir-a','/dir-b']);

API

isEmptyDir(dirPath, options?)

• dirPath (string | string[]): Path(s) to the directory/directories
• options (object, optional):
  • ignore (Array<string|RegExp|Function>): Patterns or functions to ignore files (default: [])
  • followSymlinks (boolean): Whether to follow symbolic links (default: false)
• Returns: Promise<boolean> (true only if all provided directories are empty after ignore rules)

isEmptyDir(dirPath, callback) / isEmptyDir(dirPath, options, callback)

• Callback signature: (err, result) => void
• Uses Node-style error-first callback semantics

isEmptyDirSync(dirPath, options?)

• Same as above, but synchronous. Returns boolean.

Ignore Patterns

• String: Exact filename to ignore
• RegExp: Pattern to match filenames
• Function: (filename) => boolean custom logic

Example: Ignore dotfiles and node_modules

constempty=awaitisEmptyDir('/dir',{ignore: [/^\./,'node_modules']});

Error Handling

• Throws if dirPath is an empty string (or contains one in an array)
• Throws if the path does not exist or is not a directory
• Throws on permission errors (including inaccessible entries inside a directory)

License

MIT © 2025 opensly

Contributing

If you find a bug or have a feature request, please raise an issue.

Want to contribute? Fork the repository and create a pull request with your proposed changes!