rollup-plugin-replace-shebang

2.0.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin that preserves and relocates shebang (#!) from entry files to the output bundle. Version 2.0.0, released with breaking changes in file paths (ESM: dist/index.mjs, CJS: dist/index.cjs, types: dist/index.d.mts and dist/index.d.cts). Supports include/exclude glob patterns, template variables in shebang (${name}, ${version}), chmod auto-set executable permissions, and skipBackslash option. Ships TypeScript types, requires Rollup >= 2.0.0 and Node >= 12. Differentiators: simple API, template variables, chmod support, and pattern filtering unlike alternative plugins.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/rollup-plugin-replace-shebang/dist/index.mjs from /path/to/rollup.config.js not supported. ↓

cause Trying to require() an ESM-only package in a CommonJS context.

fix

Use import syntax or convert your config to ESM (e.g., .mjs extension or type:module in package.json).

error TypeError: replaceShebang is not a function ↓

cause Importing the package incorrectly (e.g., using a named import for default export).

fix

Use the default import: import replaceShebang from 'rollup-plugin-replace-shebang'

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

cause Package not installed as a devDependency.

fix

Run: npm install -D rollup-plugin-replace-shebang

Warnings

breaking In v2.0.0, output file paths changed: ESM from 'es/index.mjs' to 'dist/index.mjs', CJS from 'lib/index.js' to 'dist/index.cjs', types from 'typings/index.d.ts' to 'dist/index.d.mts' / 'dist/index.d.cts'. ↓

fix Update your imports or references to use the new paths: import from 'dist/index.mjs' instead of 'es/index.mjs'.

breaking v2.0.0 changed to ESM-only; CJS require() will throw an error. ↓

fix Use import syntax instead of require(). If you must use CJS, consider using dynamic import or stick with v1.x.

gotcha The 'shebang' option supports template variables ${name} and ${version}, but these are resolved from package.json which must be present in the same directory. ↓

fix Ensure package.json is accessible and contains correct name and version fields.

gotcha Setting 'skipBackslash' to true can cause issues if the shebang contains actual escape sequences that should not be preserved. ↓

fix Only enable skipBackslash when you specifically need to preserve backslash encoded newlines in the shebang.

gotcha The 'chmod' option will attempt to set executable permissions, which may fail on Windows or in restricted environments. ↓

fix Use the 'chmod' option only on Unix-like systems or handle permission errors gracefully.

Install

npm install rollup-plugin-replace-shebang

yarn add rollup-plugin-replace-shebang

pnpm add rollup-plugin-replace-shebang

Imports

default (replaceShebang)

wrong

const replaceShebang = require('rollup-plugin-replace-shebang')

correct

import replaceShebang from 'rollup-plugin-replace-shebang'

ESM-only package; use import syntax. CJS require will fail.

Options

wrong

import { Options } from 'rollup-plugin-replace-shebang' (value import)

correct

import type { Options } from 'rollup-plugin-replace-shebang'

Options is a TypeScript interface, must be imported as a type.

ShebangPluginApi

wrong

import { ShebangPluginApi } from 'rollup-plugin-replace-shebang' (value import)

correct

import type { ShebangPluginApi } from 'rollup-plugin-replace-shebang'

ShebangPluginApi is a TypeScript interface for the plugin API.

Quickstart

Demonstrates basic usage: preserving a shebang from entry file to output bundle with options shebang, skipBackslash, and chmod.

// rollup.config.js
import replaceShebang from 'rollup-plugin-replace-shebang'

export default {
  input: 'src/cli.js',
  output: {
    file: 'dist/cli.js',
    format: 'es'
  },
  plugins: [
    replaceShebang({
      shebang: '#!/usr/bin/env node',
      skipBackslash: true,
      chmod: true
    })
  ]
}