Recursive Directory Creation Utility

3.0.0 · active · verified Sun Apr 19

mk-dirs is a minimalistic, Promise-based utility designed for recursively creating directories in Node.js, functioning as an `mkdir -p` equivalent. Currently stable at version 3.0.0, it differentiates itself by being exceptionally lightweight (381B to 419B gzipped) and having zero external dependencies, offering a faster alternative to packages like `mkdirp` and `make-dir`. It provides both an asynchronous (default) and a synchronous opt-in mode, catering to different application needs and Node.js versions (>=8.x for async, >=6.x for sync). While Node.js v10.12.0+ includes native `fs.mkdir` with a `recursive` option, `mk-dirs` maintains its value through a consistent, promise-based API and `cwd` option. Its release cadence is not explicitly stated but typically follows a "release when needed" pattern for such focused utilities.

Common errors

```
TypeError: (0 , mk_dirs__WEBPACK_IMPORTED_MODULE_0__.mkdir) is not a function
```
cause Attempting to call the module object directly, or incorrect destructuring of the named 'mkdir' export in ESM or CJS.

fix For ESM, ensure you use `import { mkdir } from 'mk-dirs';`. For CommonJS, use `const { mkdir } = require('mk-dirs');`.
```
UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch().
```
cause The `mkdir` function returns a Promise, and its rejection was not handled by an `await` within a `try/catch` block or a `.catch()` method.

fix Wrap async calls in a `try...catch` block (`await mkdir(...);`) or chain a `.catch(err => { /* handle error */ })` to the Promise return.
```
Error: EPERM: operation not permitted, mkdir '/path/to/dir'
```
cause Insufficient file system permissions for the current user to create directories at the specified path, or an incorrect `mode` option was applied.

fix Run the process with appropriate user permissions, verify the target directory is writable, or ensure the `mode` option is correctly specified in octal format (e.g., `0o777`).

Warnings

gotcha Native Node.js support for recursive directory creation makes external libraries like mk-dirs potentially redundant for simple use cases. Node.js v10.12.0 and above include `fs.mkdir` and `fs.mkdirSync` with a `{ recursive: true }` option, offering built-in functionality.
Fix: Consider using Node.js's native `fs.promises.mkdir` or `fs.mkdirSync` with `{ recursive: true }` for new projects or when migrating older code, unless `mk-dirs`'s specific features (like the 'cwd' option) are required.
gotcha The synchronous API requires an explicit import path: `mk-dirs/sync`. Importing from the default `mk-dirs` will always provide the asynchronous, Promise-based API.
Fix: To use the synchronous version, ensure your import statement is `import { mkdir } from 'mk-dirs/sync';` for ESM or `const { mkdir } = require('mk-dirs/sync');` for CommonJS.
gotcha Directory permissions (`options.mode`) must be specified in octal format, not decimal. Incorrectly formatted modes can lead to unexpected permissions or errors.
Fix: Always prefix octal numbers with '0o', e.g., `0o755` instead of `755`. The default is `0o777 & (~process.umask())`.

Install

npm install mk-dirs npm
yarn add mk-dirs yarn
pnpm add mk-dirs pnpm

Imports

mkdir (async ESM)
wrong:
```
import mkdir from 'mk-dirs';
```
correct:
```
import { mkdir } from 'mk-dirs';
```
This is the primary asynchronous API for ES Modules. It is a named export, not a default export.
mkdir (async CJS)
wrong:
```
const mkdir = require('mk-dirs');
```
correct:
```
const { mkdir } = require('mk-dirs');
```
This is the primary asynchronous API for CommonJS environments. Ensure you destructure the 'mkdir' function from the module object.
mkdir (sync ESM)
wrong:
```
import { mkdir } from 'mk-dirs';
```
correct:
```
import { mkdir } from 'mk-dirs/sync';
```
For synchronous operation, you must import specifically from `mk-dirs/sync`. Importing from the default path will yield the asynchronous API.

Quickstart

Demonstrates asynchronous recursive directory creation using both async/await and Promise chaining, including the use of a custom `cwd` option.

import { mkdir } from 'mk-dirs';
import { resolve } from 'path';

async function createDirectories() {
  const baseDir = process.cwd();
  console.log(`Current working directory: ${baseDir}`);

  // Async/await usage
  try {
    let output1 = await mkdir('foo/bar/baz');
    console.log(`Created directory (async/await): ${output1}`);

    // Using `cwd` option
    let customCwd = resolve(baseDir, 'temp/custom');
    let output2 = await mkdir('alpha/beta', { cwd: customCwd });
    console.log(`Created directory with custom cwd: ${output2}`);
  } catch (err) {
    console.error('Error during async/await mkdir:', err);
  }

  // Promise chain usage
  mkdir('another/path/deeply')
    .then(output => {
      console.log(`Created directory (Promise chain): ${output}`);
    })
    .catch(err => {
      console.error('Error during Promise chain mkdir:', err);
    });
}

createDirectories();

view raw JSON →