{"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,"search_vec":"'0.1.3':25 '0.19.0':36 'antongolub':70 'api':32 'boilerpl':59 'build':11 'cadenc':65 'collect':6 'current':23 'develop':63 'differenti':41 'earli':28 'esbuild':2,12,35,61,77 'esbuild-plugin-util':1 'file':15 'function':9 'getfileslist':48 'getoutputfil':49 'handl':22 'helper':46,80 'high':44 'high-level':43 'includ':14 'irregular':67 'javascript':76 'key':40 'level':45 'like':47 'limit':31 'maintain':68 'monorepo':75 'output':21 'parsecontentslayout':57 'part':72 'plugin':3,13,62,78 'poc':29 'provid':42 'read':17 'readfil':50 'reduc':58 'releas':64 'renderlist':55 'requir':34 'resolveentrypointspath':54 'scan':16 'ship':37 'surfac':33 'transform':19 'transformfil':51 'type':39 'typescript':38,81 'util':4,8,79 'version':24 'write':18 'writefil':52,53","created_at":"2026-04-27T16:59:05.501521+00:00","updated_at":"2026-04-27T16:59:05.501521+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/antongolub/misc","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/esbuild-plugin-utils","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-18","next_check":"2026-07-26","install_tag":null}}