esbuild-copy-static-files

0.1.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin (v0.1.0, stable) to copy static files from a source to destination directory only when files have changed (by MD5 hash). No third-party dependencies, purely uses Node.js standard library. Primarily designed to avoid unnecessary file copies during development with live-reloading tools. Differs from alternatives like `esbuild-plugin-copy` by focusing on change detection and minimal configuration.

Common errors

error TypeError: copyStaticFiles is not a function ↓

cause Using named import instead of default import.

fix

Use const copyStaticFiles = require('esbuild-copy-static-files') or import copyStaticFiles from 'esbuild-copy-static-files'.

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

cause Source directory does not exist or path is incorrect.

fix

Ensure src path exists relative to the build script. Use absolute paths or verify directory structure.

error Error [ERR_FS_CP_FIFO_PIPE]: Cannot copy a FIFO or pipe ↓

cause Filter includes a special file (FIFO/pipe) that cannot be copied.

fix

Update filter to exclude FIFO/pipe files: filter: (src) => !fs.statSync(src).isFIFO()

Warnings

gotcha Plugin uses Node's fs.cpSync which is only available in Node 16.7.0+. ↓

fix Use Node.js 16.7.0 or higher. Check your Node version with `node --version`.

gotcha The plugin copies files synchronously; this can block the event loop during large copies. ↓

fix If you have many static files, consider alternative async plugins like `esbuild-plugin-copy`.

gotcha The `filter` option receives absolute paths; relative comparisons may fail. ↓

fix Use path.basename or path.relative for filtering instead of simple string checks.

gotcha When `force: false` and destination exists, the operation throws even if `errorOnExist` is false (contrary to Node docs). ↓

fix Set `force: true` or `errorOnExist: false` explicitly to avoid errors.

Install

npm install esbuild-copy-static-files

yarn add esbuild-copy-static-files

pnpm add esbuild-copy-static-files

Imports

default

wrong

import copyStaticFiles from 'esbuild-copy-static-files'

correct

const copyStaticFiles = require('esbuild-copy-static-files')

Package uses CommonJS; no ESM exports available. Use require() or wrap in default import if using ESM.

copyStaticFiles

wrong

import { copyStaticFiles } from 'esbuild-copy-static-files'

correct

import copyStaticFiles from 'esbuild-copy-static-files'

Named import is incorrect; the module exports a single function as default.

esbuild plugin usage
wrong
```
plugins: [new copyStaticFiles()]
```
correct
```
plugins: [copyStaticFiles()]
```
copyStaticFiles is a factory function, not a constructor. Do not use `new`.

Quickstart

Configures esbuild with the plugin to copy static files from './static' to './out', skipping '.bak' files.

const esbuild = require('esbuild');
const copyStaticFiles = require('esbuild-copy-static-files');

require('fs').writeFileSync('./static/test.txt', 'hello');

esbuild.build({
  entryPoints: ['./app.js'],
  outfile: './out/app.js',
  bundle: true,
  plugins: [
    copyStaticFiles({
      src: './static',
      dest: './out',
      filter: (src) => !src.endsWith('.bak'),
      force: true,
    }),
  ],
}).catch(() => process.exit(1));

// Verify: fs.existsSync('./out/test.txt') // true