esbuild-plugin-copy-watch

2.3.1 verified Fri May 01 auth: no javascript

An esbuild plugin that copies files from specified source patterns to a destination directly within the esbuild build process. Version 2.3.1 is the current stable release, with active maintenance as of 2024. It supports glob patterns and optional exclusion filters, allowing developers to copy assets like static files, configs, or HTML alongside bundled JavaScript output. Unlike manual copy steps or post-build scripts, this plugin integrates with esbuild's watch mode to re-copy files on each rebuild. It also offers a `forceCopyOnRebuild` option to force recopy even when sources are unchanged. TypeScript types are included for better IDE support.

Common errors

error Error: Could not resolve 'esbuild-plugin-copy-watch' ↓

cause Package not installed or missing from node_modules

fix

Run: npm install esbuild-plugin-copy-watch

error TypeError: copy is not a function ↓

cause Using CommonJS require instead of ESM import, or calling the default export incorrectly

fix

Use import copy from 'esbuild-plugin-copy-watch' and ensure your project is ESM (type: module in package.json)

error Error: esbuild version 0.8.0 or higher is required ↓

cause Plugin requires esbuild >=0.8.0; current installed esbuild is older

fix

Update esbuild: npm install esbuild@latest

Warnings

breaking Default export changed from named export to default export in v2.0.0 ↓

fix Use default import: import copy from 'esbuild-plugin-copy-watch'

deprecated The option 'forceCopyOnRebuild' may be removed in future versions; no deprecation warning yet but usage is discouraged ↓

fix Set forceCopyOnRebuild to true if needed; see docs for alternative

gotcha Plugin requires esbuild >=0.8.0; older esbuild versions may cause build failures ↓

fix Update esbuild to version 0.8.0 or later

gotcha Glob patterns with negation must be in array form; passing a string with negation will not work ↓

fix Wrap pattern and negation in an array: ['src/**', '!src/private.js']

Install

npm install esbuild-plugin-copy-watch

yarn add esbuild-plugin-copy-watch

pnpm add esbuild-plugin-copy-watch

Imports

default

wrong

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

correct

import copy from 'esbuild-plugin-copy-watch'

ESM-only; CommonJS require will not work. Use import or dynamic import.

copyPlugin (if named export)
```
import { copy as copyPlugin } from 'esbuild-plugin-copy-watch'
```
Export is default only; there is no named export. Verified that only default export exists.
with TypeScript
wrong
```
import copy from 'esbuild-plugin-copy-watch/dist/index.js'
```
correct
```
import copy from 'esbuild-plugin-copy-watch'
```
TypeScript types are bundled in package; direct import from module root is correct.

Quickstart

Copies files matching 'static/**' to a 'static' directory in the output, and copies config JS files excluding 'private.js', with no force recopy.

import esbuild from 'esbuild'
import copy from 'esbuild-plugin-copy-watch'

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    copy({
      paths: [
        { from: 'static/**', to: 'static' },
        { from: ['config/*.js', '!config/private.js'], to: 'config' },
      ],
      forceCopyOnRebuild: false,
    })
  ]
})