cpx

What is cpx?

The cpx npm package is a tool for copying files and directories with various options. It is useful for tasks such as copying files during a build process, synchronizing directories, and more.

What are cpx's main functionalities?

Copy files from source to destination

This command copies all files and directories from the 'src' directory to the 'dist' directory. The glob pattern 'src/**/*' matches all files and directories recursively.

cpx 'src/**/*' dist

Watch mode

This command copies files from 'src' to 'dist' and continues to watch for changes. When a file in the 'src' directory is modified, it will be copied to the 'dist' directory automatically.

cpx 'src/**/*' dist --watch

Include and exclude patterns

This command copies only JavaScript files from 'src' to 'dist', excluding any files that match the '*.test.js' pattern.

cpx 'src/**/*' dist --include='*.js' --exclude='*.test.js'

Clean destination before copying

This command cleans the 'dist' directory before copying files from 'src' to 'dist'. This ensures that the destination directory is empty before the new files are copied.

cpx 'src/**/*' dist --clean

Other packages similar to cpx

copyfiles

The copyfiles package is another tool for copying files and directories. It offers similar functionality to cpx, including support for glob patterns and options for flattening directory structures. However, it does not have a built-in watch mode.

ncp

The ncp (Node Copy) package is a simple utility for copying files and directories. It is known for its ease of use and reliability. Unlike cpx, ncp does not support glob patterns or watch mode, but it is a solid choice for straightforward copy operations.

fs-extra

The fs-extra package extends the native Node.js fs module with additional methods, including methods for copying files and directories. It provides a more comprehensive set of file system utilities compared to cpx, but it requires more setup and code to achieve similar tasks.

README

cpx

Copy file globs, watching for changes.

This module provides a CLI tool like cp, but with watching.

(This module is dogfooding currently.)

Installation

npm install cpx

Usage

Usage: cpx <source> <dest> [options]

  Copy file globs, watching for changes.

    <source>  A file glob of target files.
              e.g. src/**/*.{html,png,jpg}
    <dest>    A path of destination directory.
              e.g. app

Options:

  -c, --command <command>   A command text to transform each file.
  -C, --clean               Clean files that matches <source> like pattern in
                            <dest> directory before the first copying.
  -h, --help                Print usage information
  -t, --transform <name>    A module name to transform each file. cpx lookups
                            the specified name via "require()".
  -v, --verbose             Print copied/removed files.
  -V, --version             Print the version number
  -w, --watch               Watch for files that matches <source>, and copy the
                            file to <dest> every changing.

Example

cpx src/**/*.{html,png,jpg} app --watch

This example will copy html/png/jpg files from src directory to app directory, keeping file tree structure. And every time the files are changed, copy them.

You can use together Browserify.

cpx src/**/*.{html,png,jpg} app -w & watchify src/index.js -o app/index.js

You can use shell commands to convert each file.

cpx src/**/*.js app -w -c "babel --source-maps-inline"

You can use the transform packages for Browserify.

cpx src/**/*.js app -w -t babelify -t uglifyify

It maybe can use to add header comment, to optimize images, or etc...

Node.js API

You can use this module as a node module.

var cpx = require("cpx");

cpx.copy(source: string, dest: string, cb?: (err: Error|null) => void): cpx.Cpx

Copy files that matches with source glob string to dest directory.

cpx.copySync(source: string, dest: string): void

A synchronous function of cpx.copy.

cpx.watch(source: string, dest: string): cpx.Cpx

Copy files that matches with source glob string to dest directory.

Class cpx.Cpx

cpx.Cpx is EventEmitter.

• .on("copy", (e) => { ... }) : Be fired after file is copied. e.srcPath is a path of original file. e.dstPath is a path of new file.
• .on("remove", (e) => { ... }) : Be fired after file is removed. e.path is a path of removed file.
• .on("watch-raedy", () => { ... }) : Be fired when started watching files, after the first copying.
• .on("watch-error", (err) => { ... }) : Be fired when occured errors during watching.