Registry / devops / esbuild-plugin-utils

esbuild-plugin-utils

library0.1.3jsnpmunverified

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.

devops serialization

npm install esbuild-plugin-utils

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-UTI

esbuild-plugin-utils

devopsjavascriptv0.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getFilesList

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

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

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

getOutputFiles

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

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

Named export from package root, not a subpath.

transformFile

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

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

Export is lowerCamelCase; case-sensitive in TypeScript.

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');

Debug

Known issues

gotchaPackage 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.

affects: <1.0.0

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

fix

Upgrade esbuild to >=0.19.0.

affects: >=0.1.0

gotchagetOutputFiles 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.

affects: >=0.1.0

deprecatedwriteFile is a standalone function, but future versions may rename it or change signature.

fix

Use writeFiles with an array to future-proof.

affects: >=0.1.0 <0.2.0

gotchatransformFile'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.

affects: >=0.1.0

Errors

Common errors & fixes

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.

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.

TypeError: getOutputFiles is not a function

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'.

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

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.

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; provides the build API and types used by utilities like getOutputFiles.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/antongolub/misc ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-utils ↗