Registry / devops / rollup-plugin-shebang-bin

rollup-plugin-shebang-bin

library0.1.0jsnpmunverified

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.

devops

npm install rollup-plugin-shebang-bin

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-SHEB

rollup-plugin-shebang-bin

devopsjavascriptv0.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

shebang

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

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

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

shebang default export

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

✗ 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)

✓ import type { ShebangOptions } from 'rollup-plugin-shebang-bin'

✗ import { ShebangOptions } from 'rollup-plugin-shebang-bin'

ShebangOptions is a type export only. Use import type to avoid runtime import errors. Not available in CJS.

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

Debug

Known issues

breakingSince 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().

affects: >=0.1.0

deprecatedRollup 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.

affects: >=0.1.0

gotchaIf 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.

affects: >=0.0.1

gotchaThe 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.

affects: >=0.0.1

gotchaThe 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.

affects: >=0.0.1

Errors

Common errors & fixes

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

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.

TypeError: shebang is not a function

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

fix

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

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

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.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

rolluprequiredPeer dependency; plugin is designed to work as a Rollup plugin, and requires Rollup to be installed in the project.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/prantlf/rollup-plugin-shebang-bin ↗

packagehttps://www.npmjs.com/package/rollup-plugin-shebang-bin ↗