rollup-plugin-preserve-shebangs

0.2.0 verified Mon Apr 27 auth: no javascript maintenance

Rollup plugin that preserves shebang lines (e.g., #!/usr/bin/env node) in bundled output files. Version 0.2.0, last released in 2023. It solves Rollup's inability to parse shebangs by stripping them before compilation and re-adding them to the final output. A lightweight alternative to manual workarounds or community forks. Supports Rollup 2+ and 3+ via peer dependency. Ships TypeScript definitions. No active development, but stable for its niche use case.

Common errors

error Error: Unexpected character '#' ↓

cause Rollup cannot parse shebang line as JavaScript.

fix

Add preserveShebangs() plugin to rollup config.

error Module not found: Error: Can't resolve 'rollup-plugin-preserve-shebangs' ↓

cause Plugin not installed or incorrect import path.

fix

Run npm install rollup-plugin-preserve-shebangs --save-dev and check import statement.

Warnings

gotcha Plugin must be the first plugin in the plugins array to strip shebang before other transformations. ↓

fix Move preserveShebangs() to the beginning of the plugins list.

gotcha Only works with shebang as the very first line of the file (byte order mark (BOM) before shebang may cause issues). ↓

fix Remove BOM from input files or use a BOM-stripping plugin first.

deprecated Plugin is unmaintained since 2023; no updates for Rollup 4 compatibility verified. ↓

fix Test with Rollup 4; if broken, consider manually handling shebang via banner option or custom plugin.

Install

npm install rollup-plugin-preserve-shebangs

yarn add rollup-plugin-preserve-shebangs

pnpm add rollup-plugin-preserve-shebangs

Imports

preserveShebangs

wrong

const { default: preserveShebangs } = require('rollup-plugin-preserve-shebangs')

correct

import { preserveShebangs } from 'rollup-plugin-preserve-shebangs'

Named export. ESM or CJS both work.

default import

wrong

const preserveShebangs = require('rollup-plugin-preserve-shebangs')

correct

import preserveShebangs from 'rollup-plugin-preserve-shebangs'

Default export is also available for convenience.

type
```
import type { RollupPreserveShebangsOptions } from 'rollup-plugin-preserve-shebangs'
```
TypeScript types are included, but not exported explicitly. Use the plugin's function type inference.

Quickstart

Example Rollup config using preserveShebangs plugin to handle shebang in CLI entry point.

// rollup.config.js
import { preserveShebangs } from 'rollup-plugin-preserve-shebangs';

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