copy-dir, copyfiles, cpx, fs-extra, ncp, and rimraf are Node.js packages commonly used in frontend build pipelines to handle file system operations—particularly copying, moving, or cleaning files and directories. While some focus exclusively on copying (like copyfiles and cpx), others offer broader utilities (fs-extra) or specialize in deletion (rimraf). These tools integrate into scripts for asset bundling, static site generation, or deployment preparation, often invoked via npm scripts or task runners.
File and Directory Operations in Frontend Build Pipelines: A Practical Comparison
Frontend developers routinely need to copy assets, clean output folders, or sync static files during builds. The packages copy-dir, copyfiles, cpx, fs-extra, ncp, and rimraf each solve parts of this puzzle—but with very different scopes, APIs, and trade-offs. Let’s break down how they work in real-world scenarios.
📁 Core Capabilities: What Each Package Actually Does
copy-dir copies entire directories recursively—but synchronously and without options.
// copy-dir: sync only, no globs
const copydir = require('copy-dir');
copydir.sync('src/assets', 'dist/assets');
copyfiles focuses on copying files via glob patterns while maintaining relative paths.
# copyfiles: CLI with glob support
npx copyfiles -u 1 "src/**/*.{png,jpg}" dist/
cpx provides async copying with globbing, watch mode, and promise support.
# cpx: CLI with watch
npx cpx "public/**/*" dist/ --watch
// cpx: programmatic usage
const cpx = require("cpx");
cpx.copy("src/images/*.svg", "dist/img", { preserve: true });
fs-extra is a full filesystem toolkit including copy(), move(), remove(), and more.
// fs-extra: robust programmatic copy
const { copy } = require('fs-extra');
await copy('src/static', 'dist/static', { overwrite: true });
ncp was an early async recursive copier—but is now deprecated.
// ncp: DO NOT USE in new code
const ncp = require('ncp');
ncp('old/', 'new/', err => { /* ... */ }); // Unmaintained!
rimraf deletes directories recursively—nothing more.
// rimraf: safe rm -rf
const rimraf = require('rimraf');
rimraf.sync('dist');
# Often used in npm scripts
"clean": "rimraf dist"
🔍 Filtering and Glob Support: Precision Matters
When copying assets, you rarely want everything. How do these tools handle selective copying?
copyfiles excels here with intuitive glob-to-structure mapping:
# Copies src/components/Button/icon.png → dist/components/Button/icon.png
npx copyfiles -u 2 "src/components/**/icon.png" dist/
cpx supports standard globs and exclusion patterns:
npx cpx "src/assets/**/*.{png,jpg}" "!src/assets/old/**" dist/assets/
fs-extra.copy() does not support globs—you must resolve paths yourself:
const { glob } = require('glob');
const { copy } = require('fs-extra');
const files = await glob('src/**/*.svg');
for (const file of files) {
const dest = file.replace('src', 'dist');
await copy(file, dest);
}
copy-dir and ncp offer no built-in filtering—you copy entire trees or nothing.
⚙️ Programmatic vs CLI Usage
Some tools are designed for shell scripts; others for JavaScript logic.
-
CLI-optimized:
copyfiles,cpx, andrimrafwork seamlessly inpackage.jsonscripts:{ "scripts": { "build": "rimraf dist && copyfiles -u 1 "src/public/**" dist && tsc" } } -
Programmatic-first:
fs-extraintegrates naturally into custom build tools or Gulp-like pipelines:// In a custom builder await fs.emptyDir('dist'); await fs.copy('src/html', 'dist'); await bundleJS(); -
Hybrid:
cpxoffers both CLI and API, but its programmatic interface is less feature-rich thanfs-extra.
🧹 Cleanup Workflows: Why rimraf Stands Alone
None of the copying tools handle deletion well—except rimraf, which does only that, and does it reliably across platforms:
// Windows-safe recursive delete
const rimraf = require('rimraf');
rimraf('node_modules/.cache', () => console.log('Cleaned'));
Trying to delete with fs-extra.remove() works too, but rimraf remains the de facto standard in frontend tooling due to its simplicity and legacy adoption.
⚠️ Critical Caveats and Deprecations
ncpis deprecated. Its npm page states: "This module is no longer maintained." Usefs-extra.copy()instead.copy-diris synchronous only. This blocks the event loop—unacceptable in larger projects or CI environments.fs-extra.copy()follows symlinks by default, which may cause infinite loops. Use{ dereference: false }if needed.cpxandcopyfilesdon’t remove stale files. If you deletesrc/image.png, the olddist/image.pngremains—consider pairing with a clean step.
💡 Real-World Recommendation Patterns
For simple npm script workflows:
{
"scripts": {
"clean": "rimraf dist",
"copy:assets": "copyfiles -u 1 "src/public/**/*" dist",
"build": "npm run clean && npm run copy:assets && rollup -c"
}
}
→ Use rimraf + copyfiles
For programmatic build tools (e.g., custom bundler plugins):
await fs.emptyDir(outDir);
await fs.copy(path.resolve(__dirname, 'static'), path.join(outDir, 'static'));
→ Use fs-extra
For dev-time asset watching:
npx cpx "src/assets/**" dist/assets --watch
→ Use cpx
✅ Summary: When to Reach for Which Tool
| Task | Best Choice | Why |
|---|---|---|
| Recursive directory copy (sync) | copy-dir | Only if you control inputs and sync is acceptable |
| Glob-based file copying | copyfiles | Simple, CLI-friendly, preserves structure |
| Watch-mode asset sync | cpx | Built-in watch, modern glob support |
| Full filesystem operations | fs-extra | Reliable, promise-based, handles edge cases |
| Recursive deletion | rimraf | Industry standard for rm -rf in JS |
| Legacy async copy | Avoid ncp | Deprecated—migrate to fs-extra |
Choose based on whether your workflow lives in shell scripts or JavaScript—and whether you need just copying, or a full suite of filesystem utilities.
- fs-extra:
Choose
fs-extrawhen you need a robust, general-purpose filesystem toolkit that includes recursive copy (copy()), move, ensureDir, and more—all with Promise support and graceful error handling. It’s the go-to for programmatic build logic in custom scripts or tooling where reliability and flexibility outweigh minimalism. Avoid it only if you strictly need a CLI-only solution with zero runtime dependencies. - rimraf:
Choose
rimrafexclusively when your task is recursive directory deletion (the Unixrm -rfequivalent). It has no copying capabilities but is often paired with copiers in build scripts (e.g., cleandistbefore copying assets). Its battle-tested implementation handles Windows path quirks reliably, making it a standard dependency in frontend toolchains for cleanup steps. - ncp:
Do not choose
ncpfor new projects—it is officially deprecated and unmaintained. While it once provided async recursive copying with basic filtering, its lack of updates means unresolved bugs and missing modern Node.js compatibility. Migrate existing usage tofs-extra.copy()orcpxdepending on whether you need programmatic control or CLI convenience. - copyfiles:
Choose
copyfileswhen your primary need is to copy files matching glob patterns while preserving directory structure relative to a base path. It shines in build scripts that move compiled assets (e.g., CSS, images) fromsrctodist. Its CLI-first design integrates cleanly with npm scripts but offers limited programmatic control or advanced options like transform hooks. - cpx:
Choose
cpxif you want a modern, promise-based copier with strong glob support, watch mode, and clean CLI ergonomics. It’s ideal for development workflows requiring live asset syncing (e.g., copying SVGs during dev server reloads). However, it doesn’t handle directory removal or non-copy filesystem tasks, so pair it with other tools for full pipeline coverage. - copy-dir:
Choose
copy-dirif you need a minimal, synchronous utility strictly for recursive directory copying with no dependencies. It’s useful in simple CLI scripts where async behavior isn’t required and you control the source/target structure tightly. However, it lacks filtering, glob support, or error resilience, making it unsuitable for complex or production-grade workflows.
Node.js: fs-extra
fs-extra adds file system methods that aren't included in the native fs module and adds promise support to the fs methods. It also uses graceful-fs to prevent EMFILE errors. It should be a drop in replacement for fs.
Why?
I got tired of including mkdirp, rimraf, and ncp in most of my projects.
Installation
npm install fs-extra
Usage
CommonJS
fs-extra is a drop in replacement for native fs. All methods in fs are attached to fs-extra. All fs methods return promises if the callback isn't passed.
You don't ever need to include the original fs module again:
const fs = require('fs') // this is no longer necessary
you can now do this:
const fs = require('fs-extra')
or if you prefer to make it clear that you're using fs-extra and not fs, you may want
to name your fs variable fse like so:
const fse = require('fs-extra')
you can also keep both, but it's redundant:
const fs = require('fs')
const fse = require('fs-extra')
NOTE: The deprecated constants fs.F_OK, fs.R_OK, fs.W_OK, & fs.X_OK are not exported on Node.js v24.0.0+; please use their fs.constants equivalents.
ESM
There is also an fs-extra/esm import, that supports both default and named exports. However, note that fs methods are not included in fs-extra/esm; you still need to import fs and/or fs/promises seperately:
import { readFileSync } from 'fs'
import { readFile } from 'fs/promises'
import { outputFile, outputFileSync } from 'fs-extra/esm'
Default exports are supported:
import fs from 'fs'
import fse from 'fs-extra/esm'
// fse.readFileSync is not a function; must use fs.readFileSync
but you probably want to just use regular fs-extra instead of fs-extra/esm for default exports:
import fs from 'fs-extra'
// both fs and fs-extra methods are defined
Sync vs Async vs Async/Await
Most methods are async by default. All async methods will return a promise if the callback isn't passed.
Sync methods on the other hand will throw if an error occurs.
Also Async/Await will throw an error if one occurs.
Example:
const fs = require('fs-extra')
// Async with promises:
fs.copy('/tmp/myfile', '/tmp/mynewfile')
.then(() => console.log('success!'))
.catch(err => console.error(err))
// Async with callbacks:
fs.copy('/tmp/myfile', '/tmp/mynewfile', err => {
if (err) return console.error(err)
console.log('success!')
})
// Sync:
try {
fs.copySync('/tmp/myfile', '/tmp/mynewfile')
console.log('success!')
} catch (err) {
console.error(err)
}
// Async/Await:
async function copyFiles () {
try {
await fs.copy('/tmp/myfile', '/tmp/mynewfile')
console.log('success!')
} catch (err) {
console.error(err)
}
}
copyFiles()
Methods
Async
- copy
- emptyDir
- ensureFile
- ensureDir
- ensureLink
- ensureSymlink
- mkdirp
- mkdirs
- move
- outputFile
- outputJson
- pathExists
- readJson
- remove
- writeJson
Sync
- copySync
- emptyDirSync
- ensureFileSync
- ensureDirSync
- ensureLinkSync
- ensureSymlinkSync
- mkdirpSync
- mkdirsSync
- moveSync
- outputFileSync
- outputJsonSync
- pathExistsSync
- readJsonSync
- removeSync
- writeJsonSync
NOTE: You can still use the native Node.js methods. They are promisified and copied over to fs-extra. See notes on fs.read(), fs.write(), & fs.writev()
What happened to walk() and walkSync()?
They were removed from fs-extra in v2.0.0. If you need the functionality, walk and walkSync are available as separate packages, klaw and klaw-sync.
Third Party
CLI
fse-cli allows you to run fs-extra from a console or from npm scripts.
TypeScript
If you like TypeScript, you can use fs-extra with it: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/fs-extra
File / Directory Watching
If you want to watch for changes to files or directories, then you should use chokidar.
Obtain Filesystem (Devices, Partitions) Information
fs-filesystem allows you to read the state of the filesystem of the host on which it is run. It returns information about both the devices and the partitions (volumes) of the system.
Misc.
- fs-extra-debug - Send your fs-extra calls to debug.
- mfs - Monitor your fs-extra calls.
Hacking on fs-extra
Wanna hack on fs-extra? Great! Your help is needed! fs-extra is one of the most depended upon Node.js packages. This project
uses JavaScript Standard Style - if the name or style choices bother you,
you're gonna have to get over it :) If standard is good enough for npm, it's good enough for fs-extra.
What's needed?
- First, take a look at existing issues. Those are probably going to be where the priority lies.
- More tests for edge cases. Specifically on different platforms. There can never be enough tests.
- Improve test coverage.
Note: If you make any big changes, you should definitely file an issue for discussion first.
Running the Test Suite
fs-extra contains hundreds of tests.
npm run lint: runs the linter (standard)npm run unit: runs the unit testsnpm run unit-esm: runs tests forfs-extra/esmexportsnpm test: runs the linter and all tests
When running unit tests, set the environment variable CROSS_DEVICE_PATH to the absolute path of an empty directory on another device (like a thumb drive) to enable cross-device move tests.
Windows
If you run the tests on the Windows and receive a lot of symbolic link EPERM permission errors, it's
because on Windows you need elevated privilege to create symbolic links. You can add this to your Windows's
account by following the instructions here: http://superuser.com/questions/104845/permission-to-make-symbolic-links-in-windows-7
However, I didn't have much luck doing this.
Since I develop on Mac OS X, I use VMWare Fusion for Windows testing. I create a shared folder that I map to a drive on Windows.
I open the Node.js command prompt and run as Administrator. I then map the network drive running the following command:
net use z: "\\vmware-host\Shared Folders"
I can then navigate to my fs-extra directory and run the tests.
Naming
I put a lot of thought into the naming of these functions. Inspired by @coolaj86's request. So he deserves much of the credit for raising the issue. See discussion(s) here:
- https://github.com/jprichardson/node-fs-extra/issues/2
- https://github.com/flatiron/utile/issues/11
- https://github.com/ryanmcgrath/wrench-js/issues/29
- https://github.com/substack/node-mkdirp/issues/17
First, I believe that in as many cases as possible, the Node.js naming schemes should be chosen. However, there are problems with the Node.js own naming schemes.
For example, fs.readFile() and fs.readdir(): the F is capitalized in File and the d is not capitalized in dir. Perhaps a bit pedantic, but they should still be consistent. Also, Node.js has chosen a lot of POSIX naming schemes, which I believe is great. See: fs.mkdir(), fs.rmdir(), fs.chown(), etc.
We have a dilemma though. How do you consistently name methods that perform the following POSIX commands: cp, cp -r, mkdir -p, and rm -rf?
My perspective: when in doubt, err on the side of simplicity. A directory is just a hierarchical grouping of directories and files. Consider that for a moment. So when you want to copy it or remove it, in most cases you'll want to copy or remove all of its contents. When you want to create a directory, if the directory that it's suppose to be contained in does not exist, then in most cases you'll want to create that too.
So, if you want to remove a file or a directory regardless of whether it has contents, just call fs.remove(path). If you want to copy a file or a directory whether it has contents, just call fs.copy(source, destination). If you want to create a directory regardless of whether its parent directories exist, just call fs.mkdirs(path) or fs.mkdirp(path).
Credit
fs-extra wouldn't be possible without using the modules from the following authors:
License
Licensed under MIT
Copyright (c) 2011-2024 JP Richardson