{"id":22219,"library":"rollup-plugin-shebang-bin","title":"rollup-plugin-shebang-bin","description":"A Rollup plugin (v0.1.0, last updated Dec 2024) for preserving or inserting shebang (#!) lines and setting executable permissions on output files. Supports Rollup 2, 3, and 4 via peer dependency. Configurable patterns, shebang string, separator, insert/preserve behavior, and file mode. Unlike simpler shebang plugins, this one allows separate control over preservation and insertion, plus executable mode setting. Ships TypeScript types and supports both ESM and CJS. Requires Node 14+, actively maintained with a history of dependency upgrades and Rollup version support.","status":"active","version":"0.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/prantlf/rollup-plugin-shebang-bin","tags":["javascript","rollup","plugin","rollup-plugin","shebang","hashbang","bin","executable","typescript"],"install":[{"cmd":"npm install rollup-plugin-shebang-bin","lang":"bash","label":"npm"},{"cmd":"yarn add rollup-plugin-shebang-bin","lang":"bash","label":"yarn"},{"cmd":"pnpm add rollup-plugin-shebang-bin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin is designed to work as a Rollup plugin, and requires Rollup to be installed in the project.","package":"rollup","optional":false}],"imports":[{"note":"Package is ESM-only since v0.1.0. Use import syntax. CJS require() will fail.","wrong":"const shebang = require('rollup-plugin-shebang-bin')","symbol":"shebang","correct":"import shebang from 'rollup-plugin-shebang-bin'"},{"note":"The package exports a default function, not a named export. Named import will result in undefined.","wrong":"import { shebang } from 'rollup-plugin-shebang-bin'","symbol":"shebang default export","correct":"import shebang from 'rollup-plugin-shebang-bin'"},{"note":"ShebangOptions is a type export only. Use import type to avoid runtime import errors. Not available in CJS.","wrong":"import { ShebangOptions } from 'rollup-plugin-shebang-bin'","symbol":"ShebangOptions type (TypeScript)","correct":"import type { ShebangOptions } from 'rollup-plugin-shebang-bin'"}],"quickstart":{"code":"// rollup.config.js\nimport shebang from 'rollup-plugin-shebang-bin';\n\nexport default {\n  input: 'src/cli.js',\n  output: {\n    dir: 'bin',\n    format: 'cjs'\n  },\n  plugins: [\n    shebang({\n      shebang: '#!/usr/bin/env node',\n      preserve: true,\n      insert: true,\n      executable: true,\n      mode: 0o755,\n      include: ['**/*.js'],\n      exclude: []\n    })\n  ]\n};\n// Then run: rollup -c","lang":"javascript","description":"Minimal rollup config using the plugin with all options explicitly set."},"warnings":[{"fix":"Use import syntax instead of require(). If using CommonJS, migrate to ESM or use dynamic import().","message":"Since v0.1.0, the package is ESM-only and requires Node >= 14.18. CJS require() will throw.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Upgrade to Rollup 3 or 4 if possible, as older versions may drop support.","message":"Rollup 2 support is still present but may be removed in a future major version. The peer dependency allows ^2 || ^3 || ^4.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Set preserve: true or insert: true to avoid unintended shebang removal.","message":"If both preserve and insert are false, the shebang is removed entirely. Users often expect at least one to be true.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Check your umask (run 'umask' in shell) and adjust mode accordingly, e.g., mode: 0o755 for executable scripts.","message":"The mode option is masked by process.umask. Setting mode: 0o777 may result in different actual permissions.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Pass custom regexp, e.g., regexp: /^#!/ for strict shebang detection.","message":"The regexp option default matches shebangs with any interpreter. If you have a custom shebang pattern (e.g., #!/usr/bin/python), it will be preserved. If you need to detect specific interpreters, adjust regexp.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use import statement instead of require(), or set type: 'module' in package.json and rename file to .mjs.","cause":"Using CommonJS require() to import an ESM-only module (v0.1.0+).","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"Use default import: import shebang from 'rollup-plugin-shebang-bin'","cause":"Attempting to use named import { shebang } instead of default import.","error":"TypeError: shebang is not a function"},{"fix":"Run npm install rollup-plugin-shebang-bin --save-dev and ensure Node >= 14.18.","cause":"Package not installed, or using an older Node version that doesn't resolve ESM properly.","error":"Error: Cannot find module 'rollup-plugin-shebang-bin'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}