{"id":21284,"library":"esbuild-plugin-utils","title":"esbuild-plugin-utils","description":"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.","status":"active","version":"0.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/antongolub/misc","tags":["javascript","esbuild","plugin","utils","helpers","typescript"],"install":[{"cmd":"npm install esbuild-plugin-utils","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; provides the build API and types used by utilities like getOutputFiles.","package":"esbuild","optional":false}],"imports":[{"note":"Package is ESM-only; CommonJS require may fail in Node <20.","wrong":"const getFilesList = require('esbuild-plugin-utils').getFilesList","symbol":"getFilesList","correct":"import { getFilesList } from 'esbuild-plugin-utils'"},{"note":"Named export from package root, not a subpath.","wrong":"import { getOutputFiles } from 'esbuild-plugin-utils/getOutputFiles'","symbol":"getOutputFiles","correct":"import { getOutputFiles } from 'esbuild-plugin-utils'"},{"note":"Export is lowerCamelCase; case-sensitive in TypeScript.","wrong":"import { TransformFile } from 'esbuild-plugin-utils'","symbol":"transformFile","correct":"import { transformFile } from 'esbuild-plugin-utils'"}],"quickstart":{"code":"import { getFilesList, readFiles, transformFile, writeFiles } from 'esbuild-plugin-utils';\nimport path from 'path';\n\nconst dir = process.cwd();\nconst files = await getFilesList(dir, true);\nconst entries = await readFiles(files.slice(0, 3));\nconst transformed = await Promise.all(entries.map(e =>\n  transformFile(e, [\n    {\n      pattern: /\\.txt$/,\n      transform: (content: string) => content.toUpperCase(),\n      rename: (filePath: string) => filePath.replace('.txt', '.TXT'),\n    }\n  ])\n));\nawait writeFiles(transformed, { outdir: path.join(dir, 'out') });\nconsole.log('Done');","lang":"typescript","description":"Scans directory for files, reads first 3, applies uppercase transform with rename, and writes output to 'out' subdirectory."},"warnings":[{"fix":"Pin to exact version and test upgrades thoroughly.","message":"Package is in PoC stage; API may change in minor or patch updates without major version bump.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Upgrade esbuild to >=0.19.0.","message":"Requires esbuild >=0.19.0; using with older esbuild versions will cause TypeScript or runtime errors.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Check buildResult.outputFiles before passing, or provide a fallback path.","message":"getOutputFiles expects either buildResult.outputFiles (array) or a filesystem path string; passing undefined will crash.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use writeFiles with an array to future-proof.","message":"writeFile is a standalone function, but future versions may rename it or change signature.","severity":"deprecated","affected_versions":">=0.1.0 <0.2.0"},{"fix":"Use a synchronous operation within callbacks, or wrap in a custom async transform before calling transformFile.","message":"transformFile's transform and rename callbacks are synchronous; async transformations not supported.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Switch to ES modules (e.g., set type: 'module' in package.json or use .mjs extension) and use import syntax.","cause":"Using CommonJS require() to load an ESM-only package.","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."},{"fix":"Use named imports: import { getOutputFiles } from 'esbuild-plugin-utils'.","cause":"Named export not imported correctly (e.g., import * as utils from 'esbuild-plugin-utils' and calling utils.getOutputFiles()).","error":"TypeError: getOutputFiles is not a function"},{"fix":"Install the package: npm install esbuild-plugin-utils. Ensure TypeScript version >=4.0 and no conflicting moduleResolution.","cause":"Package is not installed or TypeScript cannot resolve types (missing tsconfig paths).","error":"Cannot find module 'esbuild-plugin-utils' or its corresponding type declarations."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}