# @npmcli/fs

> filesystem utilities for the npm cli

Latest version **6.0.0** (published 2026-05-15) · ISC license · 0 weekly downloads

## Install

```sh
npm install @npmcli/fs
pnpm add @npmcli/fs
yarn add @npmcli/fs
bun add @npmcli/fs
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 6.0.0 |
| Published | 2026-05-15 |
| First published | 2021-08-25 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | ^22.22.2 \|\| ^24.15.0 \|\| >=26.0.0 |
| Dependencies | 1 |
| Unpacked size | 26 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 29 |
| Author | GitHub Inc. |
| Maintainers | saquibkhan, npm-cli-ops, reggi, owlstronaut |
| Keywords | npm, oss |

## Links

- npm: https://www.npmjs.com/package/@npmcli/fs
- Repository: https://github.com/npm/fs
- Homepage: https://github.com/npm/fs#readme
- Issues: https://github.com/npm/fs/issues
- npm.io page: https://npm.io/package/@npmcli/fs

## Dependencies (1)

- [semver](https://npm.io/package/semver.md) ^7.3.5

## Recent versions

- 6.0.0 (latest) — 2026-05-15
- 5.0.0 — 2025-10-23
- 4.0.0 — 2024-09-23
- 3.1.1 — 2024-05-07
- 3.1.0 — 2022-11-03
- 3.0.0 — 2022-10-12
- 2.1.2 — 2022-08-15
- 2.1.1 — 2022-07-20
- 2.1.0 — 2022-03-21
- 2.0.1 — 2022-02-23
- 2.0.0 — 2022-02-23
- 1.1.1 — 2022-02-10
- 1.1.0 — 2021-12-09
- 1.0.0 — 2021-08-25

## README

# @npmcli/fs

polyfills, and extensions, of the core `fs` module.

## Features

- `fs.cp` polyfill for node < 16.7.0
- `fs.withTempDir` added
- `fs.readdirScoped` added
- `fs.moveFile` added

## `fs.withTempDir(root, fn, options) -> Promise`

### Parameters

- `root`: the directory in which to create the temporary directory
- `fn`: a function that will be called with the path to the temporary directory
- `options`
  - `tmpPrefix`: a prefix to be used in the generated directory name

### Usage

The `withTempDir` function creates a temporary directory, runs the provided
function (`fn`), then removes the temporary directory and resolves or rejects
based on the result of `fn`.

```js
const fs = require('@npmcli/fs')
const os = require('os')

// this function will be called with the full path to the temporary directory
// it is called with `await` behind the scenes, so can be async if desired.
const myFunction = async (tempPath) => {
  return 'done!'
}

const main = async () => {
  const result = await fs.withTempDir(os.tmpdir(), myFunction)
  // result === 'done!'
}

main()
```

## `fs.readdirScoped(root) -> Promise`

### Parameters

- `root`: the directory to read

### Usage

Like `fs.readdir` but handling `@org/module` dirs as if they were
a single entry.

```javascript
const { readdirScoped } = require('@npmcli/fs')
const entries = await readdirScoped('node_modules')
// entries will be something like: ['a', '@org/foo', '@org/bar']
```

## `fs.moveFile(source, dest, options) -> Promise`

A fork of [move-file](https://github.com/sindresorhus/move-file) with
support for Common JS.

### Highlights

- Promise API.
- Supports moving a file across partitions and devices.
- Optionally prevent overwriting an existing file.
- Creates non-existent destination directories for you.
- Automatically recurses when source is a directory.

### Parameters

- `source`: File, or directory, you want to move.
- `dest`: Where you want the file or directory moved.
- `options`
  - `overwrite` (`boolean`, default: `true`): Overwrite existing destination file(s).

### Usage

The built-in
[`fs.rename()`](https://nodejs.org/api/fs.html#fs_fs_rename_oldpath_newpath_callback)
is just a JavaScript wrapper for the C `rename(2)` function, which doesn't
support moving files across partitions or devices. This module is what you
would have expected `fs.rename()` to be.

```js
const { moveFile } = require('@npmcli/fs');

(async () => {
	await moveFile('source/unicorn.png', 'destination/unicorn.png');
	console.log('The file has been moved');
})();
```

---
_Source: https://npm.io/package/@npmcli/fs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._