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().
import { readdir } from "node:fs/promises"; const names = await readdir("./src"); console.log(names.sort());
Try 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.
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
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
readdirmakes 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. Withrecursive: truethe 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 olderdirent.pathproperty is deprecated.- Dirent types come from the directory listing, so
isFile()andisDirectory()cost nothing. A symlink reportsisSymbolicLink()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
.jsfiles undersrc",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.