esbuild-plugin-utils

0.1.3 verified Mon Apr 27 auth: no javascript

A collection of utility functions for building esbuild plugins, including file scanning, reading, writing, transforming, and output handling. Current version 0.1.3 is an early PoC with limited API surface. Requires esbuild >=0.19.0. Ships TypeScript types. Key differentiators: provides high-level helpers like getFilesList, getOutputFiles, readFiles, transformFile, writeFile, writeFiles, resolveEntryPointsPaths, renderList, and parseContentsLayout, reducing boilerplate for esbuild plugin development. Release cadence is irregular; maintained by antongolub as part of a monorepo.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/esbuild-plugin-utils/dist/index.mjs from /path/to/project/index.js not supported. ↓

cause Using CommonJS require() to load an ESM-only package.

fix

Switch to ES modules (e.g., set type: 'module' in package.json or use .mjs extension) and use import syntax.

error TypeError: getOutputFiles is not a function ↓

cause Named export not imported correctly (e.g., import * as utils from 'esbuild-plugin-utils' and calling utils.getOutputFiles()).

fix

Use named imports: import { getOutputFiles } from 'esbuild-plugin-utils'.

error Cannot find module 'esbuild-plugin-utils' or its corresponding type declarations. ↓

cause Package is not installed or TypeScript cannot resolve types (missing tsconfig paths).

fix

Install the package: npm install esbuild-plugin-utils. Ensure TypeScript version >=4.0 and no conflicting moduleResolution.

Warnings

gotcha Package is in PoC stage; API may change in minor or patch updates without major version bump. ↓

fix Pin to exact version and test upgrades thoroughly.

breaking Requires esbuild >=0.19.0; using with older esbuild versions will cause TypeScript or runtime errors. ↓

fix Upgrade esbuild to >=0.19.0.

gotcha getOutputFiles expects either buildResult.outputFiles (array) or a filesystem path string; passing undefined will crash. ↓

fix Check buildResult.outputFiles before passing, or provide a fallback path.

deprecated writeFile is a standalone function, but future versions may rename it or change signature. ↓

fix Use writeFiles with an array to future-proof.

gotcha transformFile's transform and rename callbacks are synchronous; async transformations not supported. ↓

fix Use a synchronous operation within callbacks, or wrap in a custom async transform before calling transformFile.

Install

npm install esbuild-plugin-utils

yarn add esbuild-plugin-utils

pnpm add esbuild-plugin-utils

Imports

getFilesList

wrong

const getFilesList = require('esbuild-plugin-utils').getFilesList

correct

import { getFilesList } from 'esbuild-plugin-utils'

Package is ESM-only; CommonJS require may fail in Node <20.

getOutputFiles

wrong

import { getOutputFiles } from 'esbuild-plugin-utils/getOutputFiles'

correct

import { getOutputFiles } from 'esbuild-plugin-utils'

Named export from package root, not a subpath.

transformFile

wrong

import { TransformFile } from 'esbuild-plugin-utils'

correct

import { transformFile } from 'esbuild-plugin-utils'

Export is lowerCamelCase; case-sensitive in TypeScript.

Quickstart

Scans directory for files, reads first 3, applies uppercase transform with rename, and writes output to 'out' subdirectory.

import { getFilesList, readFiles, transformFile, writeFiles } from 'esbuild-plugin-utils';
import path from 'path';

const dir = process.cwd();
const files = await getFilesList(dir, true);
const entries = await readFiles(files.slice(0, 3));
const transformed = await Promise.all(entries.map(e =>
  transformFile(e, [
    {
      pattern: /\.txt$/,
      transform: (content: string) => content.toUpperCase(),
      rename: (filePath: string) => filePath.replace('.txt', '.TXT'),
    }
  ])
));
await writeFiles(transformed, { outdir: path.join(dir, 'out') });
console.log('Done');