TypeScript File Copy Plugin

The typescript-file-copy-plugin is a TypeScript transformer plugin that copies files or directories as part of the TypeScript build process. This removes the need for additional build tools or scripts to handle file copying operations.

It leverages the cpx2 module to handle file copying, including support for glob patterns, making it flexible for a variety of file copy operations.

This plugin has been tested against TypeScript version 5.

Prerequisites: ts-patch

This plugin requires ts-patch to be installed and set up first. ts-patch allows for custom TypeScript transformations by patching the TypeScript compiler.

Installing ts-patch

To install ts-patch, run the following command:

npm install --save-dev ts-patch

For more details on setting up ts-patch, refer to the ts-patch documentation.

There are two ways to patch the TypeScript compiler:

1. Using the CLI

You can change your tsc to tspc instead.

{
  "scripts": {
    "build": "tspc --project tsconfig.json"
  }
}

2. Using the prepare Script

You can instead patch the TypeScript compiler by adding this script to your package.json, allowing you to continue using tsc as normal:

{
  "scripts": {
    "prepare": "ts-patch install -s"
  }
}

Installation

npm install --save-dev typescript-file-copy-plugin

Usage

Configuration

To configure the plugin, you need to add it to your tsconfig.json file under the compilerOptions.plugins section. The copy option is an array of objects, where each object specifies a source (src) and a destination (dest). The src and dest fields can include glob patterns for flexible file and directory copying.

Here is an example of how to configure the plugin:

{
  "compilerOptions": {
    "plugins": [
      {
        "transform": "typescript-file-copy-plugin",
        "copy": [
          {
            "src": "src/assets/*",
            "dest": "dist/assets"
          },
          {
            "src": "src/config.json",
            "dest": "dist/config.json"
          }
        ]
      }
    ]
  }
}

Example Configurations

1. Copy a Single File:

   {
     "transform": "typescript-file-copy-plugin",
     "copy": [
       {
         "src": "src/single-file.txt",
         "dest": "dist/single-file.txt"
       }
     ]
   }

2. Copy an Entire Directory:

   {
     "transform": "typescript-file-copy-plugin",
     "copy": [
       {
         "src": "src/directory/*",
         "dest": "dist/directory"
       }
     ]
   }

3. Copy Files Matching a Wildcard Pattern:

   {
     "transform": "typescript-file-copy-plugin",
     "copy": [
       {
         "src": "src/wildcard/*.txt",
         "dest": "dist/wildcard"
       }
     ]
   }

4. Recursive Copy Using Double Wildcard Pattern:

   {
     "transform": "typescript-file-copy-plugin",
     "copy": [
       {
         "src": "src/double-wildcard/**/*",
         "dest": "dist/double-wildcard"
       }
     ]
   }

5. Copy Source File to Destination File:

   {
     "transform": "typescript-file-copy-plugin",
     "copy": [
       {
         "src": "src/single-file.txt",
         "dest": "dist/single-file-copy.txt"
       }
     ]
   }