copyFileToDest - Build Tools

Overview

copyFileToDest is a utility for copy one or more files of any type into destination directories.

This utility is file-type agnostic and can be used to copy any kind of asset, including CSS, JavaScript, JSON, images, fonts, or other static files.

The function supports:
- Copying a single file using a single configuration object.
- Copying multiple files using an array or a Set of configuration objects.
- When using a Set, it is recommended to use createCopyFileToDestParameterSet() to ensure proper TypeScript inference and autocomplete support.

Why use this?

Copy static assets directly into your build output directories.
Organize files using custom target folders or output roots.
Rename files during copy for cleaner distribution structure.
Supports batch copying with arrays or Set configurations.
Useful for CSS, JavaScript, JSON, images, fonts, and other static assets.

Importing

import { copyFileToDest } from "@rzl-zone/build-tools";

const { copyFileToDest } = require("@rzl-zone/build-tools");

Syntax

copyFileToDest(
  param: CopyFileToDestParam,
  options?: CopyFileToDestOptions
): Promise<void>

copyFileToDest(pattern, options?): Promise<void>

Parameters

Prop

Type

`param`

The parameter options for copying a file.

A single CopyFileToDestParam object, an array, or a Set of CopyFileToDestParam.

When a collection is provided:
- Each item is validated independently.
- Files are copied sequentially.
- Logging reflects the cumulative copy progress.

Example:

TypeScript/JavaScript

import {
  copyFileToDest,
  createCopyFileToDestParameterSet,
  type CopyFileToDestParam
} from "@rzl-zone/build-tools";

// Copy single file.
await copyFileToDest({source: "src/assets/logo.png", target: "dist/assets/images"});

// Copy multiple file using array.
await copyFileToDest([
    { source: "src/assets/logo.png", target: "dist/assets/images" },
    { source: "src/assets/style.css", target: "dist/assets/styles" },
  ]
);

// Copy multiple files using Set.
// ⚠️ Requires explicit typing for proper inference.
await copyFileToDest(new Set<CopyFileToDestParam>([
  {
    source: "src/config/a.json",
    target: "config"
  },
  {
    source: "src/config/b.json",
    target: "config"
  }
]));

// Recommended: using helper for Set (better DX).
await copyFileToDest(
  createCopyFileToDestParameterSet([
    {
      source: "src/config/a.json",
      target: "config"
    },
    {
      source: "src/config/b.json",
      target: "config"
    }
  ])
);

`source`

Description:
Path to the source file to be copied, can be either an absolute path or a path relative to the project root.
Required:
Type:
string
Default:
-
Example:
TypeScript/JavaScript
await copyFileToDest({ source: "src/assets/logo.png" });

`target`

target:
Target directory where the file will be copied.
Required:
Type:
string
Default:
-
Example:
TypeScript/JavaScript
await copyFileToDest({ target: "dist/assets/images", source: "src/assets/logo.png" });

Notes

When absoluteTarget is false (default), this path is resolved relative to outputRoot.
When absoluteTarget is true, this path is treated as an absolute path relative to the project root.

`fileName`

fileName:
Optional custom file name for the copied file.
Required:
Type:
string
Default:
undefined
Example:
TypeScript/JavaScript
await copyFileToDest({ fileName: "logo-new.png", target: "dist/assets/images", source: "src/assets/logo.png" });

Note

If omitted, the original file name from source will be preserved.

`outputRoot`

outputRoot:
Output root directory used when resolving the target path.
Required:
Type:
string
Default:
"dist"
Example:
TypeScript/JavaScript
await copyFileToDest({ outputRoot: "build", });

Note

When absoluteTarget is false, the final copy destination will be <project-root>/<outputRoot>/<target>.

`absoluteTarget`

absoluteTarget:
Use this when you want to copy directly to an absolute path inside the project, bypassing the outputRoot prefix.
Required:
Type:
boolean
Default:
false
Example:
TypeScript/JavaScript
await copyFileToDest({ absoluteTarget: true, });

Note

When true, disables outputRoot prefixing and treats target as an absolute path relative to the project root.

`ignoreMissingSourceError`

ignoreMissingSourceError:
When true, suppresses errors when the source file does not exist.
Required:
Type:
boolean
Default:
false
Example:
TypeScript/JavaScript
await copyFileToDest({ ignoreMissingSourceError: true, });

Notes

Instead of throwing or logging an error, the operation will be skipped.
Useful in development or watch mode where build outputs may not be immediately available.

`options`

Optional configuration object that defines how the utility function should behave in various scenarios, allowing customization and greater control at runtime.

`logLevel`

Description:
Controls how detailed the logger output should be during execution.
Supported values
- silent ➔ no output.
- error ➔ errors only.
- info ➔ standard logs (default).
- debug ➔ verbose logs.
Notes
- Invalid values are automatically reset to default.
- All levels include error output except silent.
Required:
Type:
"error" | "silent" | "info" | "debug"
Default:
"info"

Example:

TypeScript/JavaScript

// Minimal output (errors only)
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  logLevel: "error"
});

// Debug mode (verbose logs)
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  logLevel: "debug"
});

// Silent mode (no logs)
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  logLevel: "silent"
});

Helper

`createCopyFileToDestParameterSet`

Creates a Set of parameters for copy-file-to-dest.

Utility helper to construct a Set of CopyFileToDestParam with proper type inference and editor autocomplete support.

This is primarily useful when passing parameters as a Set, since directly using new Set([...]) may result in poor TypeScript inference and missing autocomplete for object literals.

Behavior:
- Accepts a single parameter or an array of parameters.
- Automatically normalizes the input into a Set.

Example:

TypeScript/JavaScript

import { copyFileToDest, createCopyFileToDestParameterSet } from "@rzl-zone/build-tools";

// single item
const setA = createCopyFileToDestParameterSet({
  source: "dist/index.d.ts",
  target: "dist"
});

// multiple items
const setB = createCopyFileToDestParameterSet([
  {
    source: "dist/a.d.ts",
    target: "dist"
  },
  {
    source: "dist/b.d.ts",
    target: "dist"
  }
]);

// usage with copyFileToDest
await copyFileToDest(setB);

// or directly usage without creating a new variable
await copyFileToDest(
  createCopyFileToDestParameterSet([
    {
      source: "src/config/a.json",
      target: "config"
    },
    {
      source: "src/config/b.json",
      target: "config"
    }
  ])
);

Returns

Returns a Promise<void>.
The function performs asynchronous file processing and does not return any value.

Version information

Since: v0.0.7.
Category: copy.
Stability: ✅ Stable (Production-ready).

Made with ❤️ by @rzl-app