Recursive File Copy Utility

Common errors

• EPERM: operation not permitted, open 'destination/path/file.txt'

  cause The Node.js process does not have sufficient write permissions to create or modify files in the specified destination directory.
  fix Ensure the process has write access to the `dest` directory and its parent folders. This might require changing directory permissions (`chmod`) or running the application with administrative privileges.

• ENOENT: no such file or directory, stat 'source/path/non-existent-file.txt'

  cause The source path (`src`) provided to `copy()` does not exist or is inaccessible.
  fix Verify that the `src` argument points to an actual, existing file or directory on the file system and that the Node.js process has read access to it.

• TypeError: Expected a 'Buffer' or 'string', but got undefined

  cause This error typically occurs within a custom `transform` stream if it attempts to pass an invalid or `undefined` chunk to the next stream stage, or doesn't properly handle `null` (end-of-stream) chunks.
  fix Review your `transform` function. Ensure it always emits `Buffer` or `string` data for file content, and correctly handles `done(null, chunk)` or `done(null, null)` for the end of a stream.

Warnings

• gotcha By default, `recursive-copy` will NOT overwrite existing files in the destination. If a file with the same name exists at the destination, the copy operation for that specific file will be skipped without an error, unless `overwrite: true` is specified.
  Fix: Set the `overwrite: true` option in the `options` object when calling `copy()` if existing files should be replaced.
• gotcha Files starting with a dot (e.g., `.env`, `.gitkeep`, `.DS_Store`) are not copied by default. This can lead to unexpected omissions if not explicitly configured.
  Fix: To include dotfiles in the copy operation, set the `dot: true` option in the `options` object.
• gotcha Symbolic links are copied as symbolic links by default (`expand: false`). If you intend to copy the *content* of the files or directories that symlinks point to, this behavior must be changed.
  Fix: Set `expand: true` in the `options` object to make `recursive-copy` resolve and copy the actual content pointed to by symbolic links, rather than the links themselves.
• gotcha Incorrectly configured `filter` options (regex, glob, or function) can lead to files being unexpectedly included or excluded. Glob patterns are relative to the `src` directory, which can be a common source of error.
  Fix: Thoroughly test your `filter` options on a small dataset. For glob patterns, ensure they correctly reflect paths relative to your `src` directory. Consider using a `filter` function for complex logic to gain explicit control and debuggability.
• gotcha File system permissions errors (EPERM) are common when the Node.js process lacks the necessary write privileges for the destination directory, or read privileges for the source. While `graceful-fs` helps, it cannot circumvent OS-level permission restrictions.
  Fix: Ensure the Node.js process has appropriate read permissions for the source path and write permissions for the destination path. This may involve running the application with elevated privileges or adjusting directory permissions on the operating system.

Install

• npm install recursive-copy npm
• yarn add recursive-copy yarn
• pnpm add recursive-copy pnpm

Imports

• copy
  wrong:

  import { copy } from 'recursive-copy';

  correct:

  import copy from 'recursive-copy';

  The primary export is a default export, even though the variable name 'copy' is common. For CommonJS, use `const copy = require('recursive-copy');`.
• copy.events
  wrong:

  import { events } from 'recursive-copy';

  correct:

  import copy from 'recursive-copy';
  const { COPY_FILE_START, ERROR } = copy.events;

  Events are exposed as properties on the default `copy` function, not as a separate named export. Access them via `copy.events`.
• Options

  import copy, { type Options } from 'recursive-copy';

  For TypeScript users, the `Options` interface can be imported as a named type for stricter type checking when configuring copy operations.

Quickstart

This quickstart demonstrates how to recursively copy a directory, including dotfiles, with specific filters, using the promise-based `async/await` syntax. It also includes cleanup.

import copy from 'recursive-copy';
import path from 'path';
import fs from 'fs';

const sourceDir = path.join(process.cwd(), 'temp_src');
const destDir = path.join(process.cwd(), 'temp_dest');

// Create dummy source files for demonstration
fs.mkdirSync(sourceDir, { recursive: true });
fs.writeFileSync(path.join(sourceDir, 'file1.txt'), 'Hello world!');
fs.writeFileSync(path.join(sourceDir, '.dotfile'), 'Hidden content.');
fs.mkdirSync(path.join(sourceDir, 'subdir'), { recursive: true });
fs.writeFileSync(path.join(sourceDir, 'subdir', 'file2.js'), 'console.log("JS file");');

async function runCopyExample() {
  try {
    console.log(`Copying from ${sourceDir} to ${destDir}...`);
    const results = await copy(sourceDir, destDir, {
      overwrite: true, // Overwrite if destination files exist
      dot: true,     // Copy dotfiles
      filter: ['**/*', '!*.log'] // Copy all files except .log files
    });
    console.info(`Copied ${results.length} files successfully.`);
    results.forEach(op => console.log(`  - ${op.src} -> ${op.dest}`));
  } catch (error) {
    console.error('Copy failed: ' + error.message);
  } finally {
    // Clean up temporary directories
    fs.rmSync(sourceDir, { recursive: true, force: true });
    fs.rmSync(destDir, { recursive: true, force: true });
    console.log('Temporary directories cleaned up.');
  }
}

runCopyExample();