Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fsPromises.readdir() method

Reference for fsPromises.readdir() in Node.js: list a directory with await, the withFileTypes and recursive options, Dirent objects, sorting and error codes.

fsPromises.readdir(path[, options]) lists the entries of a directory and returns a promise for an array. By default the array contains names (strings). With withFileTypes: true it contains fs.Dirent objects that already know whether each entry is a file, a directory or a link, saving a stat call per entry. With recursive: true it walks the whole tree and returns paths relative to the starting directory.

The . and .. entries are never included, and the order is whatever the file system returns, so sort when you need a predictable list. For huge directories that should not be loaded all at once, use fs.opendir().

NODE
import { readdir } from "node:fs/promises";

const names = await readdir("./src");
console.log(names.sort());

Try it

Node.js Names, types and recursion

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 Finding files and handling errors

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.readdir(path[, options]): Promise<string[] | Buffer[] | fs.Dirent[]>
Name Description
path The directory. A string, Buffer or URL.
options.encoding Encoding for the returned names. Default "utf8"; "buffer" returns Buffer names.
options.withFileTypes Return Dirent objects instead of strings. Default false.
options.recursive Include entries from all subdirectories. Default false.

Returns: a promise for an array of names (relative to path when recursive), Buffers or Dirents.

Errors: ENOENT (does not exist), ENOTDIR (the path is a file), EACCES (no read permission).

Usage notes

  • Sort the result. Order differs between file systems and platforms, and readdir makes no promise. names.sort() is enough for stable output.
  • Names, not paths. Join with the directory yourself (path.join(dir, name)) before opening an entry. With recursive: true the strings are relative paths such as "docs/intro.md".
  • Dirent.parentPath (Node.js 20.12+/21.4+) gives the folder containing each entry, which is what you need after a recursive listing. The older dirent.path property is deprecated.
  • Dirent types come from the directory listing, so isFile() and isDirectory() cost nothing. A symlink reports isSymbolicLink() rather than the type of its target, and on a few file systems an entry of unknown type is reported as none of the kinds.
  • Symlinked directories are listed as entries, but check with isSymbolicLink() before assuming you can walk into them in your own code.
  • It loads everything first. A directory with millions of entries uses a lot of memory. Prefer fs.opendir(), which iterates lazily.
  • For pattern matches such as "all .js files under src", fs.glob() is shorter than filtering a recursive listing yourself.
  • Windows: names keep the case stored on disk; comparing them case-insensitively is your job.