{"id":22200,"library":"rollup-plugin-replace-shebang","title":"rollup-plugin-replace-shebang","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/saqqdy/rollup-plugin-replace-shebang","tags":["javascript","rollup","rollup-plugin","shebang","hashbang","cli","bundler","typescript"],"install":[{"cmd":"npm install rollup-plugin-replace-shebang","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-replace-shebang","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-replace-shebang","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required to function as a Rollup plugin.","package":"rollup","optional":false}],"imports":[{"note":"ESM-only package; use import syntax. CJS require will fail.","wrong":"const replaceShebang = require('rollup-plugin-replace-shebang')","symbol":"default (replaceShebang)","correct":"import replaceShebang from 'rollup-plugin-replace-shebang'"},{"note":"Options is a TypeScript interface, must be imported as a type.","wrong":"import { Options } from 'rollup-plugin-replace-shebang' (value import)","symbol":"Options","correct":"import type { Options } from 'rollup-plugin-replace-shebang'"},{"note":"ShebangPluginApi is a TypeScript interface for the plugin API.","wrong":"import { ShebangPluginApi } from 'rollup-plugin-replace-shebang' (value import)","symbol":"ShebangPluginApi","correct":"import type { ShebangPluginApi } from 'rollup-plugin-replace-shebang'"}],"quickstart":{"code":"// rollup.config.js\nimport replaceShebang from 'rollup-plugin-replace-shebang'\n\nexport default {\n  input: 'src/cli.js',\n  output: {\n    file: 'dist/cli.js',\n    format: 'es'\n  },\n  plugins: [\n    replaceShebang({\n      shebang: '#!/usr/bin/env node',\n      skipBackslash: true,\n      chmod: true\n    })\n  ]\n}","lang":"typescript","description":"Demonstrates basic usage: preserving a shebang from entry file to output bundle with options shebang, skipBackslash, and chmod."},"warnings":[{"fix":"Update your imports or references to use the new paths: import from 'dist/index.mjs' instead of 'es/index.mjs'.","message":"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'.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use import syntax instead of require(). If you must use CJS, consider using dynamic import or stick with v1.x.","message":"v2.0.0 changed to ESM-only; CJS require() will throw an error.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure package.json is accessible and contains correct name and version fields.","message":"The 'shebang' option supports template variables ${name} and ${version}, but these are resolved from package.json which must be present in the same directory.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Only enable skipBackslash when you specifically need to preserve backslash encoded newlines in the shebang.","message":"Setting 'skipBackslash' to true can cause issues if the shebang contains actual escape sequences that should not be preserved.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the 'chmod' option only on Unix-like systems or handle permission errors gracefully.","message":"The 'chmod' option will attempt to set executable permissions, which may fail on Windows or in restricted environments.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use import syntax or convert your config to ESM (e.g., .mjs extension or type:module in package.json).","cause":"Trying to require() an ESM-only package in a CommonJS context.","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."},{"fix":"Use the default import: import replaceShebang from 'rollup-plugin-replace-shebang'","cause":"Importing the package incorrectly (e.g., using a named import for default export).","error":"TypeError: replaceShebang is not a function"},{"fix":"Run: npm install -D rollup-plugin-replace-shebang","cause":"Package not installed as a devDependency.","error":"Error: Cannot find module 'rollup-plugin-replace-shebang'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}