Registry / devops / ncp

ncp

JSON →
library1.15jsnpmunverified

ncp is an asynchronous recursive file and directory copying utility for Node.js, designed to mimic the `cp -r` command but with a pure JavaScript, non-blocking implementation. The current stable version, 2.0.0, as indicated in the prompt, has not seen active development for many years (last commit 6 years ago on GitHub), suggesting it is an abandoned project with no current release cadence. Its key differentiators include a programmatic API that allows for fine-grained control over the copying process, such as setting a global concurrency limit, filtering files via regular expressions or custom functions, applying streaming transformations during the copy, and flexible error handling (either stopping on the first error or continuing while logging all errors). It offers an entirely asynchronous approach to file system operations, which was a significant advantage in early Node.js environments for non-blocking I/O compared to synchronous `cp -r` alternatives.

devops
npm install ncp
github ↗package ↗
INSTALL
IMPORT
SIG · NCP
N
ncp
devopsjavascriptv1.15
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ncp (main function)
✓ const { ncp } = require('ncp');
✗ import ncp from 'ncp'; const ncp = require('ncp');
The main `ncp` function is exported as a named property `ncp` on the module, not as the default export. This package is CommonJS-only and does not support ES Modules `import` syntax.
ncp.limit
✓ const { ncp } = require('ncp'); ncp.limit = 16;
The concurrency limit is a mutable property set directly on the imported `ncp` function object. This setting affects all subsequent `ncp` calls globally within the application.
ncp with options
✓ const { ncp } = require('ncp'); ncp(source, destination, { filter: /\.js$/, stopOnErr: true }, callback);
The `options` object allows for fine-grained control over copy behavior, including filtering, streaming transforms, overwriting behavior (`clobber`), symlink dereferencing, and specific error handling (`stopOnErr`).

This quickstart demonstrates how to use `ncp` programmatically to recursively copy a directory. It showcases setting a global concurrency limit, applying a file filter (only copying `.txt` files and directories), using a transform stream to modify file content (uppercase), and configuring `ncp` to stop immediately on the first error encountered.

const path = require('path'); const fs = require('fs'); const { ncp } = require('ncp'); // Correct import const { Transform } = require('stream'); // Define source and destination paths const sourceDir = path.join(__dirname, 'temp_source'); const destDir = path.join(__dirname, 'temp_destination'); // Ensure source directory exists and has some content fs.mkdirSync(sourceDir, { recursive: true }); fs.writeFileSync(path.join(sourceDir, 'file1.txt'), 'Hello from file 1!'); fs.writeFileSync(path.join(sourceDir, 'file2.js'), 'console.log("file 2");'); fs.mkdirSync(path.join(sourceDir, 'subdir'), { recursive: true }); fs.writeFileSync(path.join(sourceDir, 'subdir', 'subfile.txt'), 'Hello from subfile!'); console.log(`Attempting to copy from ${sourceDir} to ${destDir}`); // Set a global concurrency limit (optional) ncp.limit = 4; // Perform the copy operation with options ncp(sourceDir, destDir, { filter: function(src) { // Only copy files that end with .txt or are directories return /\.txt$/.test(src) || fs.statSync(src).isDirectory(); }, stopOnErr: true, // Stop on the first error encountered clobber: true, // Overwrite existing files transform: function (read, write) { // Example transform: convert content to uppercase const transformStream = new Transform({ transform(chunk, encoding, callback) { this.push(chunk.toString().toUpperCase()); callback(); } }); read.pipe(transformStream).pipe(write); } }, function (err) { if (err) { console.error('Copy failed:', err); // Clean up temporary directories on error fs.rmSync(sourceDir, { recursive: true, force: true }); fs.rmSync(destDir, { recursive: true, force: true }); process.exit(1); } console.log('Copy complete!'); // Verify copied files (optional) if (fs.existsSync(path.join(destDir, 'file1.txt'))) { console.log('file1.txt copied successfully (and should be uppercase):'); console.log(fs.readFileSync(path.join(destDir, 'file1.txt'), 'utf8')); } if (!fs.existsSync(path.join(destDir, 'file2.js'))) { console.log('file2.js was filtered out as expected.'); } if (fs.existsSync(path.join(destDir, 'subdir', 'subfile.txt'))) { console.log('subfile.txt copied successfully (and should be uppercase):'); console.log(fs.readFileSync(path.join(destDir, 'subdir', 'subfile.txt'), 'utf8')); } // Clean up temporary directories fs.rmSync(sourceDir, { recursive: true, force: true }); fs.rmSync(destDir, { recursive: true, force: true }); console.log('Temporary directories cleaned up.'); });
Debug
Known issues
breakingThe `ncp` package appears to be abandoned, with no commits in over six years and numerous open issues and pull requests on its GitHub repository. This means there will be no new features, bug fixes, or security patches released, making it unsuitable for new projects or environments requiring active maintenance.
fix
Consider using actively maintained alternatives such as `fs-extra` (for general file system operations, including `copy` and `copySync`) or the native Node.js `fs.cp` (available in Node.js >=16.0.0) for modern projects.
affects: >=2.0.0
gotcha`ncp` is a CommonJS-only package. Attempting to import it using ES Modules `import` syntax will result in errors (e.g., `ERR_REQUIRE_ESM`) or unexpected behavior, as it does not provide an ESM export.
fix
Always use CommonJS `require` syntax: `const { ncp } = require('ncp');`. For projects requiring ESM, consider migrating to a modern alternative.
affects: >=2.0.0
gotchaThe main `ncp` function is exposed as a *named property* on the module object (`require('ncp').ncp`), not as the default export. A common mistake is attempting to call `require('ncp')` directly.
fix
Ensure you correctly access the `ncp` property: `const { ncp } = require('ncp');` or `const ncp = require('ncp').ncp;`.
affects: >=2.0.0
gotchaSetting `ncp.limit = N` modifies a global property on the imported `ncp` function, affecting *all* subsequent `ncp` calls throughout the entire Node.js process. This can lead to unintended side effects or concurrency issues if different parts of an application expect different concurrency settings.
fix
While `ncp` itself doesn't offer a per-call concurrency option, alternatives like `fs-extra` allow concurrency settings directly within their `copy` function options, avoiding global state.
affects: >=2.0.0
gotchaBy default, `ncp` is designed to continue copying files even if errors occur, logging them along the way. This behavior differs from the standard `cp -r` command, which typically halts on the first encountered error.
fix
To make `ncp` stop on the first error, similar to `cp -r`, you must explicitly set the `options.stopOnErr` property to `true`: `ncp(source, destination, { stopOnErr: true }, callback);`.
affects: >=2.0.0
Errors
Common errors & fixes
TypeError: ncp is not a function
This error occurs when attempting to invoke the result of `require('ncp')` directly, instead of accessing the `ncp` function nested within the module export.
fix
Correct the import statement to `const { ncp } = require('ncp');` or `const ncp = require('ncp').ncp;`.
(node:xyz) MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 error listeners added to [ReadStream]. Use emitter.setMaxListeners() to increase limit
This warning typically indicates that too many file streams are being opened concurrently without being properly closed or managed, often when `ncp.limit` is set very high or a `transform` stream isn't handling backpressure correctly.
fix
Reduce the `ncp.limit` value to a lower number (e.g., 4 or 8) to decrease concurrent file operations. Ensure any custom `options.transform` streams correctly pipe data and handle stream completion/errors.
EACCES: permission denied, open 'some/path/to/file'
The Node.js process lacks the necessary read or write permissions for a specific source file, destination file, or directory during the copy operation.
fix
Verify that the user running the Node.js process has appropriate file system permissions for both the source and destination paths. You may need to change directory/file permissions or run the process with elevated privileges.
Upgrade
Version history
1.15latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/AvianFlu/ncp ↗
packagehttps://www.npmjs.com/package/ncp ↗
ncp — npm install ncp · libregistry