mkdir

Create a directory. With recursive: true, creates all parent directories; returns the first created path.

Basic usage


import { mkdir } from '@vooya/fs'
 
await mkdir('./new-dir')
await mkdir('./a/b/c', { recursive: true })
const first = await mkdir('./x/y/z', { recursive: true, mode: 0o755 }) // first created path

Methods

`mkdir(path, options?)`

Async. Returns Promise<string | undefined> (recursive: true: first created path when a directory was created).

Argument	Type	Description
`path`	string	Directory path.
`options`	object	Optional: `recursive` (boolean), `mode` (number).

`mkdirSync(path, options?)`

Sync. Same arguments; returns string | undefined when recursive.

Performance

Single-directory and recursive mkdir are atomic/serial operations. No specific benchmark in the repo; expect on-par with Node.js (small N-API overhead per call). See Benchmarks for general single-file behavior.

Notes

recursive: When true, creates parent directories as needed; does not fail if the path already exists (same as Node.js).
mode: Applied when directories are created and filtered by the process umask. Use octal (e.g. 0o755).
Known gap: Filesystem errors currently have Node-like messages, but do not expose Node-style code, path, and syscall fields yet.
Unsupported Node inputs: String mode values, Buffer paths, and URL paths are not part of the current Vooya FS mkdir surface.

Competitor measurements

See the full mkdir comparison table for Node 22/24, peer libraries, sync/Promise modes, small and batch workloads, execution routes and measurement limits.