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

const isEmptyDir = require('is-empty-dir');

(async () => {
  const empty = await isEmptyDir('/path/to/dir');
  console.log(empty); // true or false
})();

// Callback style
isEmptyDir('/path/to/dir', (err, empty) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(empty); // true or false
});

// Synchronous
const { isEmptyDirSync } = require('is-empty-dir');
const emptySync = isEmptyDirSync('/path/to/dir');
console.log(emptySync); // true or false

ES Modules

import isEmptyDir, { isEmptyDirSync } from 'is-empty-dir';

const empty = await isEmptyDir('/path/to/dir');
const emptySync = isEmptyDirSync('/path/to/dir');

Check multiple directories in one call

const allEmpty = await isEmptyDir(['/dir-a', '/dir-b']);
const allEmptySync = 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

const empty = await isEmptyDir('/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!