{"id":26081,"library":"piral-cli-esbuild","title":"Piral CLI esbuild Plugin","description":"A plugin for the Piral CLI that replaces the default bundler (webpack/parcel) with esbuild, providing faster debug and build capabilities for pilets and Piral instances. Version 1.4.0 is the current stable release, published with provenance. The plugin bundles esbuild, esbuild-sass-plugin, esbuild-codegen-plugin, and handles asset files out of the box. It requires Node.js >=20.18.1 and works with piral-cli. Key differentiators: seamless drop-in replacement, no additional config needed, and support for customization via esbuild.config.js. Recent updates include provenance, improved externals handling, and Node.js polyfills via plugins. The package ships TypeScript declarations.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/smapiot/piral-cli-esbuild","tags":["javascript","piral-cli","piral","plugin","esbuild","build","debug","bundle","typescript"],"install":[{"cmd":"npm install piral-cli-esbuild","lang":"bash","label":"npm"},{"cmd":"yarn add piral-cli-esbuild","lang":"bash","label":"yarn"},{"cmd":"pnpm add piral-cli-esbuild","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The plugin is designed to be used with piral-cli; it hooks into piral-cli's build/debug commands","package":"piral-cli","optional":false}],"imports":[{"note":"ESM-only since v1.0; CommonJS require() will fail on Node >=20.","wrong":"const piralCliEsbuild = require('piral-cli-esbuild')","symbol":"default","correct":"import piralCliEsbuild from 'piral-cli-esbuild'"},{"note":"createEsbuildConfig is a named export, not the default.","wrong":"import createEsbuildConfig from 'piral-cli-esbuild'","symbol":"createEsbuildConfig","correct":"import { createEsbuildConfig } from 'piral-cli-esbuild'"},{"note":"The correct symbol is PiletEsbuildPlugin, not PiletPlugin (no such export).","wrong":"import { PiletPlugin } from 'piral-cli-esbuild'","symbol":"PiletEsbuildPlugin","correct":"import { PiletEsbuildPlugin } from 'piral-cli-esbuild'"},{"note":"The correct symbol is PiralEsbuildPlugin, not PiralPlugin (no such export).","wrong":"import { PiralPlugin } from 'piral-cli-esbuild'","symbol":"PiralEsbuildPlugin","correct":"import { PiralEsbuildPlugin } from 'piral-cli-esbuild'"}],"quickstart":{"code":"// Install the plugin\n// npm i piral-cli-esbuild --save-dev\n\n// In your piral instance or pilet root, run:\n// piral build\n// or\n// pilet debug\n\n// To customize esbuild options, create esbuild.config.js in the root:\n// esbuild.config.js\nmodule.exports = function(options) {\n  options.plugins.push({\n    name: 'custom',\n    setup(build) {\n      build.onResolve({ filter: /^my-prefix\\// }, args => {\n        return { path: args.path.replace('my-prefix/', ''), external: true };\n      });\n    }\n  });\n  return options;\n};","lang":"javascript","description":"Demonstrates installation, basic usage (piral build/pilet debug), and how to customize esbuild config via esbuild.config.js."},"warnings":[{"fix":"Use ESM imports (import) instead of require().","message":"ESM-only since v1.0; CommonJS require() will fail on Node >=20.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade Node.js to version 20.18.1 or later.","message":"Node.js >=20.18.1 required since v1.3.0; older Node versions will not work.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Install with --save-dev flag: npm i piral-cli-esbuild --save-dev","message":"The plugin must be installed as a devDependency; it does not work if installed as a regular dependency.","severity":"gotcha","affected_versions":">=0.15.0"},{"fix":"Update your pilets to schema v3 (see Piral documentation).","message":"pilet schema v2 support dropped in v1.0.0; only schema v3 is supported.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Use module.exports = function(options) { ... return options; }","message":"esbuild.config.js must export a function that returns options; exporting an object will not work.","severity":"gotcha","affected_versions":">=0.15.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Name your config file esbuild.config.mjs or use dynamic import() inside the config.","cause":"esbuild.config.js is loaded with require() but piral-cli-esbuild is ESM-only.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/piral-cli-esbuild/index.js from /path/to/your/project/esbuild.config.js not supported."},{"fix":"Run: npm install --save-dev piral-cli-esbuild","cause":"Plugin not installed or installed as regular dependency instead of devDependency.","error":"Cannot find module 'piral-cli-esbuild'"},{"fix":"Ensure piral-cli version is compatible (>=2.0). Upgrade piral-cli if needed.","cause":"The plugin is not recognized by piral-cli, possibly wrong version of piral-cli.","error":"Error: The plugin 'piral-cli-esbuild' seems to be missing a bundler export."},{"fix":"Export a function that returns modified options: module.exports = function(options) { ... return options; }","cause":"esbuild.config.js exported an options object instead of a function modifying it.","error":"TypeError: options.plugins.push is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}