Copy files

• Fast by cloning the files whenever possible.
• Resilient by using graceful-fs.
• User-friendly by accepting globs and creating non-existent destination directories.
• User-friendly error messages.
• Progress reporting.

npm install cpy

import cpy from 'cpy';

await cpy([
	'source/*.png', // Copy all .png files
	'!source/goat.png', // Ignore goat.png
], 'destination');

// Copy node_modules to destination/node_modules
await cpy('node_modules', 'destination');

// Copy node_modules content to destination
await cpy('node_modules/**', 'destination');

// Copy node_modules structure but skip all files except .json files
await cpy('node_modules/**/*.json', 'destination');

// Copy all png files into destination without keeping directory structure
await cpy('**/*.png', 'destination', {flat: true});

// Progress reporting
await cpy('source/**', 'destination', {
	onProgress: progress => {
		console.log(`Progress: ${Math.round(progress.percent * 100)}%`);
	}
});

console.log('Files copied!');

Returns a Promise<string[]> with the destination file paths.

Type: string | string[]

Files to copy.

If any of the files do not exist, an error will be thrown (does not apply to globs).

Type: string

Destination directory.

Type: object

Options are passed to globby.

Note: Dotfiles are excluded by default. Set dot: true to include them.

In addition, you can specify the below options.

Type: string
Default: process.cwd()

Working directory to find source files.

Type: boolean
Default: true

Overwrite existing files.

Type: boolean
Default: false

Skip files when the destination path already exists.

This option takes precedence over overwrite.

Type: boolean
Default: false

Only overwrite when the source is newer, or when sizes differ with the same modification time. Ignored when overwrite is false or ignoreExisting is true.

Type: boolean
Default: false

Flatten directory structure. All copied files will be put in the same directory.

import cpy from 'cpy';

await cpy('src/**/*.js', 'destination', {
	flat: true
});

Type: 'cwd' | 'pattern'
Default: undefined

Choose how destination paths are calculated for patterns. By default, globs are resolved relative to their parent and explicit paths are resolved relative to cwd. Set to 'pattern' to make explicit paths behave like globs, or 'cwd' to make globs behave like explicit paths.

Type: string | Function

Filename or function used to rename every file in source. Use a two-argument function to receive a frozen source file object and a mutable destination file object. The destination path must stay within the original destination directory. The legacy single-argument form is deprecated, emits a warning, and will be removed in the next major release.

import cpy from 'cpy';

await cpy('foo.js', 'destination', {
	rename: (source, destination) => {
		if (source.nameWithoutExtension === 'foo') {
			destination.nameWithoutExtension = 'bar';
		}
	}
});

await cpy('foo.js', 'destination', {
	rename: (source, destination) => {
		if (source.nameWithoutExtension === 'foo') {
			destination.extension = 'ts';
		}

		console.log(destination.name);
		//=> 'foo.ts'
	}
});

await cpy('foo.js', 'destination', {
	rename: 'new-name'
});

Type: number
Default: os.availableParallelism()

Number of files being copied concurrently.

Type: boolean
Default: true

Ignores junk files.

Type: Function

Function to filter files to copy.

Receives a source file object and a context object with the resolved destination path.

Return true to include, false to exclude. You can also return a Promise that resolves to true or false.

import cpy from 'cpy';

await cpy('foo', 'destination', {
	filter: (file, {destinationPath}) => file.extension !== 'nocopy'
});

Type: Function

The given function is called whenever there is measurable progress.

import cpy from 'cpy';

await cpy('foo', 'destination', {
	onProgress: progress => {
		// …
	}
});

Type: AbortSignal

Abort signal to cancel the copy operation.

Type: boolean
Default: true

Whether to follow symbolic links.

Type: boolean
Default: false

Preserve file access and modification timestamps when copying.

Type: boolean
Default: false

Skip copying and return the resolved destination paths.

Type: string
Example: '/tmp/dir/foo.js'

Resolved path to the file.

Type: string
Example: 'dir/foo.js' if cwd was '/tmp'

Relative path to the file from cwd.

Type: string
Example: 'foo.js'

Filename with extension.

Type: string
Example: 'foo'

Filename without extension.

Type: string
Example: 'js'

File extension.

Type: string
Example: '/tmp/dir/foo.js'

Resolved destination path for the file. The directory part must stay within the original destination directory.

Type: string
Example: 'foo.js'

Filename with extension.

Type: string
Example: 'foo'

Filename without extension.

Type: string
Example: 'js'

File extension.

The onProgress option provides progress information during file copying:

import cpy from 'cpy';

await cpy(source, destination, {
	onProgress: progress => {
		console.log(`Progress: ${Math.round(progress.percent * 100)}%`);
	}
});

{
	completedFiles: number,
	totalFiles: number,
	completedSize: number,
	percent: number,
	sourcePath: string,
	destinationPath: string,
}

• completedFiles - Number of files copied so far.
• totalFiles - Total number of files to copy.
• completedSize - Number of bytes copied so far.
• percent - Progress percentage as a value between 0 and 1.
• sourcePath - Absolute source path of the current file being copied.
• destinationPath - Absolute destination path of the current file being copied.

Type: Function

Note that the .on() method is available only right after the initial cpy call, so make sure you add a handler before awaiting the promise:

import cpy from 'cpy';

await cpy(source, destination).on('progress', progress => {
	// …
});

• cpy-cli - CLI for this module
• copy-file - Copy a single file
• move-file - Move a file
• make-dir - Make a directory and its parents if needed