Piral CLI esbuild Plugin

1.4.0 verified Fri May 01 auth: no javascript

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.

Common errors

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

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

error Cannot find module 'piral-cli-esbuild' ↓

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

fix

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

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

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

error TypeError: options.plugins.push is not a function ↓

cause 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; }

Warnings

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

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

breaking Node.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.

gotcha The 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

deprecated pilet schema v2 support dropped in v1.0.0; only schema v3 is supported. ↓

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

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

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

Install

npm install piral-cli-esbuild

yarn add piral-cli-esbuild

pnpm add piral-cli-esbuild

Imports

default

wrong

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

correct

import piralCliEsbuild from 'piral-cli-esbuild'

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

createEsbuildConfig

wrong

import createEsbuildConfig from 'piral-cli-esbuild'

correct

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

createEsbuildConfig is a named export, not the default.

PiletEsbuildPlugin

wrong

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

correct

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

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

PiralEsbuildPlugin

wrong

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

correct

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

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

Quickstart

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;
};