rollup-plugin-preserve-shebang

1.0.1 verified Mon Apr 27 auth: no javascript

A Rollup plugin that automatically preserves a shebang (#!) line from your entry file in the bundle output. Version 1.0.1 is current stable, with maintenance-level activity. Key differentiator: it handles multi-entry setups and allows overriding the shebang string, unlike alternatives that only work with single entries or require manual configuration. It auto-detects the shebang from the entry file or can be explicitly set via plugin options. Supports Rollup 1+ and Node 14+. Lightweight with no dependencies.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/rollup-plugin-preserve-shebang/src/index.js from /path/to/rollup.config.js not supported. ↓

cause CommonJS require used with an ESM-only package.

fix

Use import syntax instead of require, or convert your config to ESM by adding 'type': 'module' in package.json.

error TypeError: shebang is not a function ↓

cause shebang import is the function itself, but it was not called (e.g., used shebang instead of shebang() in plugins array).

fix

Call shebang() function: plugins: [shebang()].

error Error: No shebang found in entry file 'cli.js' ↓

cause Entry file does not start with #!, and no explicit shebang option was provided.

fix

Add #!/usr/bin/env node as first line of entry file, or provide shebang option: shebang({ shebang: '#!/usr/bin/env node' }).

Warnings

gotcha The plugin only works with Rollup 1+; older versions are incompatible. ↓

fix Upgrade Rollup to version 1 or higher.

gotcha If the entry file has no shebang, the plugin does nothing—it does not add one unless explicitly set via the `shebang` option. ↓

fix Either ensure the entry file starts with #! or use the `shebang` option to provide one.

gotcha The package is ESM-only and cannot be required via CommonJS require. ↓

fix Use dynamic import() or ensure your project uses ESM (type: 'module' in package.json).

Install

npm install rollup-plugin-preserve-shebang

yarn add rollup-plugin-preserve-shebang

pnpm add rollup-plugin-preserve-shebang

Imports

default

wrong

const shebang = require('rollup-plugin-preserve-shebang')

correct

import shebang from 'rollup-plugin-preserve-shebang'

Package is ESM-only; CommonJS require will fail with ERR_REQUIRE_ESM.

default (named import)

wrong

import { shebang } from 'rollup-plugin-preserve-shebang'

correct

import shebang from 'rollup-plugin-preserve-shebang'

Only default export exists; named import will not work.

plugin usage in Rollup config
wrong
```
export default { plugins: [shebang] }
```
correct
```
export default { plugins: [shebang()] }
```
shebang must be called as a function; passing the function reference directly will cause error.

Quickstart

Shows basic usage: import the default export, call shebang() in Rollup's plugins array to preserve the shebang from the entry file.

import shebang from 'rollup-plugin-preserve-shebang';

export default {
  input: 'src/cli.js',
  output: {
    file: 'dist/cli.js',
    format: 'cjs'
  },
  plugins: [
    shebang()
  ]
};