rollup-plugin-add-shebang

0.3.1 verified Mon Apr 27 auth: no javascript maintenance

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.

Common errors

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

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

error TypeError: shebang is not a function ↓

cause 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 Error: Could not resolve 'rollup-plugin-add-shebang' ↓

cause Package not installed or missing from dependencies.

fix

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

Warnings

gotcha Plugin 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.

deprecated The 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.

gotcha Plugin 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.

gotcha If 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.

Install

npm install rollup-plugin-add-shebang

yarn add rollup-plugin-add-shebang

pnpm add rollup-plugin-add-shebang

Imports

default (shebang)

wrong

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

correct

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

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

shebang (CommonJS)

wrong

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

correct

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

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

TypeScript

wrong

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

correct

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

Package ships TypeScript types, so ESM import is preferred.

Quickstart

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'
    })
  ]
};