A Comprehensive Guide to Copying Files by Extension Using package.json Scripts

Introduction

In modern front-end development, npm is not only used for dependency management but also as a build tool to automate tasks via the scripts field in package.json. A common requirement is copying files with specific extensions, such as in TypeScript projects where only compiled .js files need to be copied from a source directory to a target, ignoring .ts and .map files. Based on Stack Overflow Q&A data, this article deeply analyzes how to efficiently achieve this, avoid common errors, and provide multiple solutions.

Problem Analysis: Limitations of the ncp Module

The user initially tried using the ncp module with regex filtering to copy only .js files. Configured in package.json as:

{
    "scripts": {
        "copy": "ncp scripts wwwroot/scripts --filter=\".*(\\.js$)\"" 
    }, 
    "devDependencies": { 
        "ncp": "2.0.0.0" 
    }
}

However, this resulted in no files being copied, even though the regex .*\.js$ correctly matched .js files in testing. The root cause lies in the complexity of string nesting and escaping for ncp's filter parameter. The user tried variants like --filter=/.*\.js$/g (compilation error) or --filter=\"/.*\.js$/g\" (no files copied), none succeeding. This indicates ncp's inadequacy in regex support, especially across platforms and script environments.

Solution: Adopting the cpx Module

As the best answer, the cpx module offers a more elegant solution. It is a CLI tool that uses glob patterns instead of regex, simplifying file matching. First, install cpx:

npm install --save-dev cpx

Then configure the script in package.json:

{
    "scripts": {
        "copy-js": "cpx 'scripts/**/*.js' wwwroot/scripts"
    },
    "devDependencies": {
        "cpx": "^1.5.0"
    }
}

Here, 'scripts/**/*.js' uses a glob pattern to match .js files in the scripts directory and all subdirectories. cpx automatically preserves the directory structure without extra parameters. Run npm run copy-js to complete the copy. Advantages of cpx include:

• Intuitive glob syntax, avoiding regex escaping issues.
• Built-in recursive copying and structure preservation.
• Active maintenance (though note project updates).
• CLI integration for easy use in npm scripts.

For example, if the source contains scripts/main.js and scripts/utils/helper.js, the target will have wwwroot/scripts/main.js and wwwroot/scripts/utils/helper.js accordingly.

Supplementary Solutions: Comparison with Other Tools

Beyond cpx, tools like copyfiles are worth considering. Install copyfiles:

npm install --save-dev copyfiles

Configuration example:

{
    "scripts": {
        "copy-js": "copyfiles -f scripts/**/*.js wwwroot/scripts"
    }
}

copyfiles uses the -f flag for flat copying (optional), but does not preserve structure by default; use the -u parameter to maintain hierarchy. For instance, copyfiles -u 1 scripts/**/*.js wwwroot/scripts preserves structure based on depth. Compared to cpx, copyfiles is lighter but may have fewer features.

Technical Details and Best Practices

When implementing file copying, note the following key points:

1. Glob Patterns vs. Regex: Globs like **/*.js match .js files in all subdirectories, being more readable and maintainable than regex. In npm scripts, ensure proper quoting to avoid shell interpretation issues.
2. Cross-Platform Compatibility: Use quotes around glob patterns (e.g., 'scripts/**/*.js') to ensure consistent operation on Windows and Unix systems.
3. Performance Considerations: For large projects, consider incremental copying or caching mechanisms, though cpx and copyfiles handle efficiency well.
4. Error Handling: Add error checks in scripts, such as using && chaining or Node.js script wrappers.

Code example: A full package.json configuration might include multiple copy tasks.

{
    "scripts": {
        "copy:js": "cpx 'src/**/*.js' dist",
        "copy:css": "copyfiles -u 1 src/**/*.css dist",
        "build": "npm run copy:js && npm run copy:css"
    },
    "devDependencies": {
        "cpx": "^1.5.0",
        "copyfiles": "^2.4.1"
    }
}

Conclusion

With the cpx module, developers can easily implement extension-based file copying tasks, avoiding regex pitfalls in ncp. Its glob support and structure preservation make it an ideal choice for npm build workflows. Meanwhile, tools like copyfiles offer alternatives for flexible selection based on project needs. Based on real Q&A data, this article extracts core knowledge to help readers quickly integrate efficient file copying strategies into their development workflows.