nx-plugin-esbuild

0.5.0 verified Fri May 01 auth: no javascript

Nx plugin for building Node.js and browser applications using ESBuild. Current stable version is 0.5.0. This package integrates ESBuild into the Nx build system as an executor, providing faster builds compared to traditional bundlers. It supports TypeScript, JSX, CSS, and code splitting. Key differentiators: native integration with @nrwl/devkit, uses ESBuild for speed, and requires @swc/core for TypeScript compilation. Release cadence is irregular; maintained by the community. It is inspired by @wanews/nx-esbuild but offers a different API and configuration style.

Common errors

error Cannot find module '@nrwl/devkit' ↓

cause Missing peer dependency @nrwl/devkit.

fix

Run 'npm install @nrwl/devkit @nrwl/workspace'.

error TypeError: EsbuildExecutor is not a constructor ↓

cause Using require() with ESM-only package or outdated import style.

fix

Use ES module import (import { EsbuildExecutor } from 'nx-plugin-esbuild'). For CJS, use dynamic import: const { EsbuildExecutor } = await import('nx-plugin-esbuild').

error Error: The 'context' object must include 'workspaceRoot' ↓

cause The second argument to EsbuildExecutor constructor is missing workspaceRoot property.

fix

Provide an object with workspaceRoot and other context properties: { projectName, root, workspaceRoot }.

Warnings

breaking The executor API changed in version 0.5.0; context object now requires workspaceRoot. ↓

fix Update to 0.5.0 and provide workspaceRoot in the executor context.

breaking Default export changed from a class to a factory function in version 0.4.0. ↓

fix Use default import as a function, not constructor.

deprecated The @swc/core peer dependency is mandatory, but SWC may be optional in future versions. ↓

fix Do not remove @swc/core until officially announced.

gotcha Requires @nrwl/devkit and @nrwl/workspace to be installed even if not directly used. ↓

fix Add these as devDependencies in your project.

gotcha TypeScript compilation relies on @swc/core, not tsc; ensure ESBuild or SWC handles decorators and other TypeScript features. ↓

fix Check SWC compatibility for your TypeScript config (e.g., decorators, experimental features).

Install

npm install nx-plugin-esbuild

yarn add nx-plugin-esbuild

pnpm add nx-plugin-esbuild

Imports

EsbuildExecutor

wrong

const EsbuildExecutor = require('nx-plugin-esbuild').EsbuildExecutor

correct

import { EsbuildExecutor } from 'nx-plugin-esbuild'

ESM-only; use dynamic import if required from CJS.

EsbuildBuildOptions

wrong

const { EsbuildBuildOptions } = require('nx-plugin-esbuild')

correct

import type { EsbuildBuildOptions } from 'nx-plugin-esbuild'

Type-only export for TypeScript users.

default

wrong

const NxPluginEsbuild = require('nx-plugin-esbuild')

correct

import NxPluginEsbuild from 'nx-plugin-esbuild'

Default export is a factory function, not a class.

Quickstart

Shows how to programmatically use the EsbuildExecutor to bundle a Node.js application.

import { EsbuildExecutor } from 'nx-plugin-esbuild';

// Example executor configuration
const options = {
  entryPoints: ['src/main.ts'],
  outfile: 'dist/main.js',
  bundle: true,
  platform: 'node',
  target: 'node14',
  tsconfig: 'tsconfig.json'
};

const executor = new EsbuildExecutor(options, {
  projectName: 'my-app',
  root: '/path/to/project',
  workspaceRoot: '/path/to/workspace'
});

await executor.execute();
console.log('Build complete!');