Registry / devops / piral-cli-esbuild

piral-cli-esbuild

library1.4.0jsnpmunverified

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.

devops

npm install piral-cli-esbuild

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PIRAL-CLI-ESBUILD

piral-cli-esbuild

devopsjavascriptv1.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

default

✓ import piralCliEsbuild from 'piral-cli-esbuild'

✗ const piralCliEsbuild = require('piral-cli-esbuild')

ESM-only since v1.0; CommonJS require() will fail on Node >=20.

createEsbuildConfig

✓ import { createEsbuildConfig } from 'piral-cli-esbuild'

✗ import createEsbuildConfig from 'piral-cli-esbuild'

createEsbuildConfig is a named export, not the default.

PiletEsbuildPlugin

✓ import { PiletEsbuildPlugin } from 'piral-cli-esbuild'

✗ import { PiletPlugin } from 'piral-cli-esbuild'

The correct symbol is PiletEsbuildPlugin, not PiletPlugin (no such export).

PiralEsbuildPlugin

✓ import { PiralEsbuildPlugin } from 'piral-cli-esbuild'

✗ import { PiralPlugin } from 'piral-cli-esbuild'

The correct symbol is PiralEsbuildPlugin, not PiralPlugin (no such export).

Demonstrates installation, basic usage (piral build/pilet debug), and how to customize esbuild config via esbuild.config.js.

// Install the plugin // npm i piral-cli-esbuild --save-dev // In your piral instance or pilet root, run: // piral build // or // pilet debug // To customize esbuild options, create esbuild.config.js in the root: // esbuild.config.js module.exports = function(options) { options.plugins.push({ name: 'custom', setup(build) { build.onResolve({ filter: /^my-prefix\// }, args => { return { path: args.path.replace('my-prefix/', ''), external: true }; }); } }); return options; };

Debug

Known issues

breakingESM-only since v1.0; CommonJS require() will fail on Node >=20.

fix

Use ESM imports (import) instead of require().

affects: >=1.0.0

breakingNode.js >=20.18.1 required since v1.3.0; older Node versions will not work.

fix

Upgrade Node.js to version 20.18.1 or later.

affects: >=1.3.0

gotchaThe plugin must be installed as a devDependency; it does not work if installed as a regular dependency.

fix

Install with --save-dev flag: npm i piral-cli-esbuild --save-dev

affects: >=0.15.0

deprecatedpilet schema v2 support dropped in v1.0.0; only schema v3 is supported.

fix

Update your pilets to schema v3 (see Piral documentation).

affects: >=1.0.0

gotchaesbuild.config.js must export a function that returns options; exporting an object will not work.

fix

Use module.exports = function(options) { ... return options; }

affects: >=0.15.0

Errors

Common errors & fixes

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.

esbuild.config.js is loaded with require() but piral-cli-esbuild is ESM-only.

fix

Name your config file esbuild.config.mjs or use dynamic import() inside the config.

Cannot find module 'piral-cli-esbuild'

Plugin not installed or installed as regular dependency instead of devDependency.

fix

Run: npm install --save-dev piral-cli-esbuild

Error: The plugin 'piral-cli-esbuild' seems to be missing a bundler export.

The plugin is not recognized by piral-cli, possibly wrong version of piral-cli.

fix

Ensure piral-cli version is compatible (>=2.0). Upgrade piral-cli if needed.

TypeError: options.plugins.push is not a function

esbuild.config.js exported an options object instead of a function modifying it.

fix

Export a function that returns modified options: module.exports = function(options) { ... return options; }

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

piral-clirequiredThe plugin is designed to be used with piral-cli; it hooks into piral-cli's build/debug commands

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/smapiot/piral-cli-esbuild ↗

packagehttps://www.npmjs.com/package/piral-cli-esbuild ↗

homepagehttps://piral.io ↗