TypeScript Copy Non-TS Files

0.1.9 · active · verified Sun Apr 19

typescript-cp is a utility designed to seamlessly copy non-TypeScript asset files into a TypeScript project's `outDir` during the build or watch process. It currently stands at version 0.1.9, indicating it's still in active development with minor releases for features and bug fixes, rather than a strict major-version-based cadence. Its core functionality integrates directly with TypeScript's project structure, honoring `tsconfig.json` configurations, particularly the `exclude` array, to prevent copying files that TypeScript itself ignores. Key differentiators include its CLI-first approach, ability to watch files for changes alongside `tsc -w`, and support for loader rules to transform asset content before copying, providing a more integrated solution than generic file copy utilities for TypeScript-specific workflows.

Common errors

```
Error: watch ENOSPC
```
cause Too many files are being watched, hitting the operating system's limit for open file descriptors.

fix Increase your system's `fs.inotify.max_user_watches` limit (Linux: `sudo sysctl -n -w fs.inotify.max_user_watches=524288`) or refine your `.tscprc` configuration to `exclude` more directories/files, especially `node_modules` (which is ignored by default but can be overridden).
```
Error: Cannot find module 'typescript-cp/dist/types' or its corresponding type declarations.
```
cause Attempting to import types from `typescript-cp` in a TypeScript environment, but the package or its types are not correctly installed or resolved.

fix Ensure `typescript-cp` is installed as a `devDependency` (`npm install typescript-cp -D`). Verify your `tsconfig.json` `moduleResolution` is set appropriately (e.g., `NodeNext` or `Node`). If using an older TypeScript version, ensure it is compatible with the package's type declarations.
```
Files are not being copied to outDir.
```
cause This often occurs because files are matched by the `tsconfig.json`'s `exclude` array, the `.tscprc`'s `ignored_files` or `compiled_files` patterns, or the source/destination paths are incorrectly configured.

fix First, check your `tsconfig.json` `exclude` array. Next, inspect your `.tscprc` file (if present) for `ignored_files` and `compiled_files` patterns. You can also run `tscp` with verbose logging (if available, check help `tscp -h`) or temporarily remove exclusion patterns to diagnose.

Warnings

gotcha The package is still pre-1.0 (currently 0.1.9), meaning minor versions (e.g., 0.x.x to 0.y.x) *can* introduce breaking changes without adhering to semantic versioning for major increments. Always review release notes when updating.
Fix: Consult the changelog (`https://github.com/body-builder/typescript-cp/releases`) for breaking changes before updating to a new minor version.
breaking Support for TypeScript 5 was introduced in v0.1.8. While this generally means improved compatibility, older versions of `typescript-cp` might not function correctly with TypeScript 5+, and conversely, newer versions might drop support for very old TypeScript versions.
Fix: Ensure your `typescript` peer dependency is compatible. If experiencing issues, update `typescript-cp` to the latest version and verify your `typescript` version meets the peer dependency requirements (currently `>=4.2.3`).
gotcha By default, `typescript-cp` respects the `exclude` array in your `tsconfig.json`. If files are not being copied as expected, verify they are not inadvertently listed in `exclude` or being ignored by default `ignored_files` patterns (e.g., `node_modules`).
Fix: Check your `tsconfig.json` `exclude` array. For fine-grained control, configure `use_ts_exclude` to `false` or adjust `ignored_files` in a `.tscprc` configuration file. Refer to the documentation on configuration options.
gotcha The package provides basic loader functionality for transforming file content. These loaders are defined in a `.tscprc.js` file and must return the modified content synchronously. Complex or asynchronous transformations are not directly supported within the loader function.
Fix: Ensure custom loaders are simple, synchronous functions that accept content and meta-data, returning the transformed content. For more complex asset pipelines, consider pre-processing files with dedicated tools before `typescript-cp` handles them.

Install

npm install typescript-cp npm
yarn add typescript-cp yarn
pnpm add typescript-cp pnpm

Imports

Config
```
import { Config } from 'typescript-cp/dist/types';
```
Used for type-checking the configuration file (`.tscprc.js`) when defining custom loader rules. This is a type import, not a runtime value.
Rule
```
import { Rule } from 'typescript-cp/dist/types';
```
Used for type-checking individual rule definitions within the `.tscprc.js` configuration. This is a type import, not a runtime value.
tscp (CLI)
wrong:
```
import tscp from 'typescript-cp';
```
correct:
```
npx tscp
```
The primary way to use `typescript-cp` is via its Command Line Interface (`tscp`), typically invoked with `npx` or as an npm script. It is not designed for direct programmatic import as a library.

Quickstart

Demonstrates `typescript-cp` integration into `package.json` scripts for both build and watch modes, running alongside `tsc`.

{
  "name": "my-ts-project",
  "version": "1.0.0",
  "description": "A sample project using typescript-cp",
  "main": "dist/index.js",
  "scripts": {
    "clean": "rm -rf dist",
    "build:ts": "tsc",
    "build:assets": "tscp",
    "build": "npm run clean && npm run build:ts && npm run build:assets",
    "watch:ts": "tsc -w",
    "watch:assets": "tscp -w",
    "start:dev": "npm run clean && npm run watch:ts & npm run watch:assets"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "typescript": ">=4.2.3",
    "typescript-cp": "^0.1.9"
  },
  "private": true
}

// To run the build:
// npm run build

// To start the dev watcher:
// npm run start:dev

view raw JSON →