Registry / devops / rollup-plugin-replace-shebang

rollup-plugin-replace-shebang

library2.0.0jsnpmunverified

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.

devops

npm install rollup-plugin-replace-shebang

github ↗package ↗

INSTALL

IMPORT

SIG · ROLLUP-PLUGIN-REPL

rollup-plugin-replace-shebang

devopsjavascriptv2.0.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.

default (replaceShebang)

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

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

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

Options

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

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

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

ShebangPluginApi

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

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

ShebangPluginApi is a TypeScript interface for the plugin API.

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

Debug

Known issues

breakingIn 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'.

affects: >=2.0.0

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

affects: >=2.0.0

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

affects: >=1.0.0

gotchaSetting '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.

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

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.

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

TypeError: replaceShebang is not a function

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: Cannot find module 'rollup-plugin-replace-shebang'

Package not installed as a devDependency.

fix

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

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

rolluprequiredPeer dependency required to function as a Rollup plugin.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/saqqdy/rollup-plugin-replace-shebang ↗

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