esbuild-copy-files-plugin

1.2.1 verified Fri May 01 auth: no javascript

An esbuild plugin to copy files and directories during builds. Current stable version is 1.0.0. The plugin is updated irregularly. Key differentiators: simple API with source/target arrays, copyWithFolder option to preserve or flatten directory structure, minimal dependencies. Suitable for copying static assets like HTML, images, or fonts alongside esbuild bundles.

Common errors

error Error: The plugin 'esbuild-copy-files-plugin' is not compatible with esbuild version 0.14.0 or higher. Please update esbuild to a compatible version. ↓

cause Older plugin versions require esbuild <0.14.0

fix

Update both packages: npm install esbuild@latest esbuild-copy-files-plugin@latest

error TypeError: copy is not a function ↓

cause Importing default instead of named export or using require without destructuring

fix

Use: import { copy } from 'esbuild-copy-files-plugin' or const { copy } = require('esbuild-copy-files-plugin')

error ENOENT: no such file or directory, copyfile '...' -> '...' ↓

cause Source path does not exist or is incorrect

fix

Verify source paths and ensure they exist relative to process.cwd()

Warnings

gotcha Empty source array causes plugin to silently do nothing. ↓

fix Ensure source array has at least one path.

gotcha copyWithFolder: false may overwrite files with same name from different sources. ↓

fix Use copyWithFolder: true or ensure unique filenames.

gotcha Recursive directory copying maintains depth; no depth limit or file filter. ↓

fix Manually list specific directories or files if full depth is undesirable.

Install

npm install esbuild-copy-files-plugin

yarn add esbuild-copy-files-plugin

pnpm add esbuild-copy-files-plugin

Imports

copy

wrong

import copy from 'esbuild-copy-files-plugin'

correct

import { copy } from 'esbuild-copy-files-plugin'

Use named import; default export not available.

copy

wrong

const copy = require('esbuild-copy-files-plugin')

correct

const { copy } = require('esbuild-copy-files-plugin')

CommonJS destructuring required.

copy

wrong

const copy = require('esbuild-copy-files-plugin').default

correct

import { copy } from 'esbuild-copy-files-plugin'

No default export in CommonJS.

Quickstart

Shows how to configure the plugin with CJS in esbuild to copy HTML and images preserving folder structure.

const esbuild = require('esbuild');
const { copy } = require('esbuild-copy-files-plugin');
esbuild.build({
  entryPoints: ['./src/index.js'],
  bundle: true,
  outfile: './dist/bundle.js',
  plugins: [
    copy({
      source: ['./src/index.html', './src/assets/images'],
      target: './dist',
      copyWithFolder: true
    })
  ]
}).catch(() => process.exit(1));