Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fsPromises.rm() and mkdir() methods

Reference for fsPromises.rm() and fsPromises.mkdir() in Node.js: create and delete whole directory trees with promises, the recursive and force options, and error codes.

fsPromises.mkdir() and fsPromises.rm() are the promise-based tools for building and tearing down directory trees. mkdir(path, { recursive: true }) creates a folder and every missing parent, like mkdir -p. rm(path, { recursive: true, force: true }) deletes a file or a whole folder with everything inside, like rm -rf.

Both live in node:fs/promises, so you call them with await and handle failures with try/catch. Their callback and synchronous cousins (fs.mkdir(), fs.rmSync()) take the same options.

NODE
import fs from "node:fs/promises";

await fs.mkdir("build/assets/img", { recursive: true });
await fs.rm("build", { recursive: true, force: true });

Try it

Node.js Create a nested tree and delete it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js The errors you will meet

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
fsPromises.mkdir(path[, options]): Promise<string | undefined>
fsPromises.rm(path[, options]): Promise<void>

mkdir() options (a number is treated as mode):

Name Description
recursive Create missing parent directories and do not fail if the directory already exists. Default false.
mode Permission bits for new directories. Default 0o777, reduced by the process umask. Ignored on Windows.

rm() options:

Name Description
recursive Remove directories and their contents. Required to delete a directory. Default false.
force Ignore a missing path (no ENOENT). Default false.
maxRetries How many times to retry on EBUSY, EMFILE, ENFILE, ENOTEMPTY or EPERM. Only used with recursive. Default 0.
retryDelay Milliseconds between retries, growing linearly. Default 100.

Returns: mkdir() resolves with the path of the first directory created when recursive is true, otherwise undefined. rm() resolves with undefined.

Errors: mkdir() rejects with EEXIST if the path exists and recursive is off, ENOENT if a parent is missing and recursive is off, and ENOTDIR if a parent is a file. rm() rejects with ENOENT for a missing path unless force is set, and with ERR_FS_EISDIR for a directory without recursive.

Usage notes

  • recursive changes the meaning of "exists". Without it, mkdir() on an existing folder fails with EEXIST. With it, the call succeeds, which makes recursive: true the usual choice for "make sure this folder exists".
  • Use the return value. With recursive: true, the resolved path tells you where the new part of the tree begins, which is useful when you want to undo only what you created. It is undefined when everything already existed.
  • force only hides a missing path. Permission errors and busy files still reject. Do not use force to paper over real failures.
  • rm() replaces two older functions. rmdir() only removes empty folders (recursive on it is deprecated), and unlink() only removes files. rm() handles both, plus whole trees.
  • Dangerous inputs. rm(path, { recursive: true, force: true }) with an empty or wrongly built path can delete far more than you meant. Build paths with path.join() from a known base and validate user input first.
  • Symbolic links are removed, not followed. rm() deletes the link itself and never the target.
  • On Windows an open file cannot be deleted. maxRetries helps when antivirus or an editor holds a file for a moment.
  • Cleaning up temp folders: pair fs.mkdtemp() with rm() in a finally block.