Registry / devops / rollup-plugin-add-shebang

rollup-plugin-add-shebang

library0.3.1jsnpmunverified

Rollup plugin that prepends a shebang line (e.g., #!/usr/bin/env node) to output files. v0.3.1 is the latest stable release (last updated July 2019). It automatically adds shebangs to matched files after bundling, supporting include/exclude patterns and custom shebang strings or functions. Unlike alternatives, it works with code splitting and doesn't require modifying source files. Currently in maintenance mode with no recent updates.

devops

npm install rollup-plugin-add-shebang

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-ADD-

rollup-plugin-add-shebang

devopsjavascriptv0.3.1

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.

default (shebang)

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

✗ import { shebang } from 'rollup-plugin-add-shebang'

Package exports a default function. Named import will not work.

shebang (CommonJS)

✓ const shebang = require('rollup-plugin-add-shebang').default

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

CJS users must use .default because the package uses ESM internally.

TypeScript

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

✗ import shebang = require('rollup-plugin-add-shebang')

Package ships TypeScript types, so ESM import is preferred.

Configures Rollup to add a Node.js shebang to output files matching cli.js or bin.js patterns.

// rollup.config.js import shebang from 'rollup-plugin-add-shebang'; export default { input: 'src/index.js', output: { dir: 'dist', format: 'cjs' }, plugins: [ shebang({ include: ['**/cli.js', '**/bin.js'], exclude: '**/node_modules/**', shebang: '#!/usr/bin/env node' }) ] };

Debug

Known issues

gotchaPlugin does not validate shebang content; invalid shebangs (e.g., missing #!) will silently produce broken executables.

fix

Always start shebang with #! and ensure correct interpreter path.

affects: >=0.1.0

deprecatedThe shebang option can be a function in v0.3.0+, but this is not documented in the README.

fix

Refer to changelog for function signature; the function receives the file path and should return a string.

affects: >=0.3.0

gotchaPlugin only runs on output files after bundling; it cannot be used to modify input files.

fix

Use source-level shebangs or another plugin if you need shebangs in source files.

affects: >=0.1.0

gotchaIf output.format is 'es' or 'iife', the shebang may be placed correctly but the module may not be directly executable; only CJS/UMD formats are reliably executable with Node.js shebang.

fix

Set output.format to 'cjs' or 'umd' when targeting Node.js CLI tools.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Invalid shebang option. Must be a string or a function that returns a string.

Provided a non-string/non-function value (e.g., number, null, or object) to the shebang option.

fix

Pass a string like '#!/usr/bin/env node' or a function returning a string.

TypeError: shebang is not a function

Imported the package incorrectly (e.g., using named import { shebang }) in an ESM context.

fix

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

Error: Could not resolve 'rollup-plugin-add-shebang'

Package not installed or missing from dependencies.

fix

Run npm install --save-dev rollup-plugin-add-shebang

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

rolluprequiredpeer dependency – plugin is designed to work as a Rollup plugin

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/ls-age/rollup-plugin-add-shebang ↗

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