esbuild-plugin-shelljs

1.1.2 verified Fri May 01 auth: no javascript

Esbuild plugin to patch shelljs at build time, making it compatible with esbuild by adding missing `.js` extensions to dynamic imports. Current version 1.1.2. Release cadence is low, as the plugin is stable. Key differentiator: solves a specific esbuild + shelljs bundling issue (extensions) without forking or modifying shelljs source. Alternatives: using `require('shelljs')` in Node.js or bundling with other tools like Webpack, but this plugin integrates cleanly into esbuild's plugin system.

Common errors

error Error: Module not found in bundle: ./src/cat ↓

cause shelljs uses dynamic imports without file extensions; esbuild cannot resolve them.

fix

Use the esbuild-plugin-shelljs plugin to patch shelljs.

error Cannot find module 'shelljs' ↓

cause shelljs is not installed or not in node_modules.

fix

Run npm install shelljs (or ensure it's in package.json).

error TypeError: shellJsPlugin is not a function ↓

cause Incorrect import: default import used instead of named import.

fix

Use import { shellJsPlugin } from 'esbuild-plugin-shelljs' (named export).

Warnings

gotcha Plugin only patches shelljs's own dynamic imports; does not fix other packages with missing extensions. ↓

fix For other packages, consider a generic esbuild-ignore or resolve alias.

deprecated Requires esbuild 0.9+ (uses `onResolve` and `onLoad` hooks). ↓

fix Ensure esbuild version is >= 0.9.

gotcha If shelljs is installed as devDependency or not installed at all, the plugin will fail to find shelljs path. ↓

fix Add shelljs as a dependency (npm install shelljs).

Install

npm install esbuild-plugin-shelljs

yarn add esbuild-plugin-shelljs

pnpm add esbuild-plugin-shelljs

Imports

shellJsPlugin
wrong
```
import shellJsPlugin from 'esbuild-plugin-shelljs'
```
correct
```
import { shellJsPlugin } from 'esbuild-plugin-shelljs'
```
This is a named export, not default. Also works with require: const { shellJsPlugin } = require('esbuild-plugin-shelljs').

require('esbuild-plugin-shelljs')

wrong

const shellJsPlugin = require('esbuild-plugin-shelljs')

correct

const { shellJsPlugin } = require('esbuild-plugin-shelljs')

CommonJS require only works if you destructure the named export.

default import

wrong

import shellJsPlugin from 'esbuild-plugin-shelljs'

correct

import { shellJsPlugin } from 'esbuild-plugin-shelljs'

There is no default export; only named.

Quickstart

Demonstrates basic usage of the shellJsPlugin in an esbuild build script to resolve shelljs dependencies.

import { shellJsPlugin } from 'esbuild-plugin-shelljs';
import esbuild from 'esbuild';
import shelljs from 'shelljs';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'out/bundle.js',
  plugins: [shellJsPlugin],
});

// Your code that uses shelljs (e.g., shelljs.ls('.')) will now bundle correctly.