rollup-plugin-shebang-bin

0.1.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin (v0.1.0, last updated Dec 2024) for preserving or inserting shebang (#!) lines and setting executable permissions on output files. Supports Rollup 2, 3, and 4 via peer dependency. Configurable patterns, shebang string, separator, insert/preserve behavior, and file mode. Unlike simpler shebang plugins, this one allows separate control over preservation and insertion, plus executable mode setting. Ships TypeScript types and supports both ESM and CJS. Requires Node 14+, actively maintained with a history of dependency upgrades and Rollup version support.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using CommonJS require() to import an ESM-only module (v0.1.0+).

fix

Use import statement instead of require(), or set type: 'module' in package.json and rename file to .mjs.

error TypeError: shebang is not a function ↓

cause Attempting to use named import { shebang } instead of default import.

fix

Use default import: import shebang from 'rollup-plugin-shebang-bin'

error Error: Cannot find module 'rollup-plugin-shebang-bin' ↓

cause Package not installed, or using an older Node version that doesn't resolve ESM properly.

fix

Run npm install rollup-plugin-shebang-bin --save-dev and ensure Node >= 14.18.

Warnings

breaking Since v0.1.0, the package is ESM-only and requires Node >= 14.18. CJS require() will throw. ↓

fix Use import syntax instead of require(). If using CommonJS, migrate to ESM or use dynamic import().

deprecated Rollup 2 support is still present but may be removed in a future major version. The peer dependency allows ^2 || ^3 || ^4. ↓

fix Upgrade to Rollup 3 or 4 if possible, as older versions may drop support.

gotcha If both preserve and insert are false, the shebang is removed entirely. Users often expect at least one to be true. ↓

fix Set preserve: true or insert: true to avoid unintended shebang removal.

gotcha The mode option is masked by process.umask. Setting mode: 0o777 may result in different actual permissions. ↓

fix Check your umask (run 'umask' in shell) and adjust mode accordingly, e.g., mode: 0o755 for executable scripts.

gotcha The regexp option default matches shebangs with any interpreter. If you have a custom shebang pattern (e.g., #!/usr/bin/python), it will be preserved. If you need to detect specific interpreters, adjust regexp. ↓

fix Pass custom regexp, e.g., regexp: /^#!/ for strict shebang detection.

Install

npm install rollup-plugin-shebang-bin

yarn add rollup-plugin-shebang-bin

pnpm add rollup-plugin-shebang-bin

Imports

shebang

wrong

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

correct

import shebang from 'rollup-plugin-shebang-bin'

Package is ESM-only since v0.1.0. Use import syntax. CJS require() will fail.

shebang default export
wrong
```
import { shebang } from 'rollup-plugin-shebang-bin'
```
correct
```
import shebang from 'rollup-plugin-shebang-bin'
```
The package exports a default function, not a named export. Named import will result in undefined.
ShebangOptions type (TypeScript)
wrong
```
import { ShebangOptions } from 'rollup-plugin-shebang-bin'
```
correct
```
import type { ShebangOptions } from 'rollup-plugin-shebang-bin'
```
ShebangOptions is a type export only. Use import type to avoid runtime import errors. Not available in CJS.

Quickstart

Minimal rollup config using the plugin with all options explicitly set.

// rollup.config.js
import shebang from 'rollup-plugin-shebang-bin';

export default {
  input: 'src/cli.js',
  output: {
    dir: 'bin',
    format: 'cjs'
  },
  plugins: [
    shebang({
      shebang: '#!/usr/bin/env node',
      preserve: true,
      insert: true,
      executable: true,
      mode: 0o755,
      include: ['**/*.js'],
      exclude: []
    })
  ]
};
// Then run: rollup -c