rollup-plugin-resolve-shebang

1.0.1 verified Mon Apr 27 auth: no javascript

A Rollup plugin that recognizes and preserves shebang (#!) lines in entry files, ensuring they remain at the top of the bundled output. Version 1.0.1 is current; ESM-only, requires Node.js >=18 or >=20, and Rollup >=4. Unlike alternatives that may strip or misplace shebangs, this plugin correctly retains them for CLI tools. Ships TypeScript types and has a minimal footprint.

Common errors

error Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'rollup-plugin-resolve-shebang' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install rollup-plugin-resolve-shebang' or 'yarn add rollup-plugin-resolve-shebang'.

error TypeError: (0 , plugin_require.resolveShebang) is not a function ↓

cause Using require() instead of import.

fix

Change to dynamic import: const { resolveShebang } = await import('rollup-plugin-resolve-shebang'); or use import at top level.

error The 'require' of ES Module not supported. ↓

cause Attempting to require() an ESM-only package.

fix

Convert your project to ESM (type: module in package.json) or use dynamic import.

Warnings

gotcha ESM-only: require() will fail on Node.js <18 or older rollup versions. ↓

fix Use import syntax and ensure Node.js >=18.0.0 or >=20.

breaking Requires Rollup >=4; older versions of Rollup are not supported. ↓

fix Upgrade Rollup to version 4 or later.

gotcha Shebang preservation only works on the entry file; chunks may not retain shebangs. ↓

fix Ensure your entry file is the one with the shebang; use manualChunks if needed.

Install

npm install rollup-plugin-resolve-shebang

yarn add rollup-plugin-resolve-shebang

pnpm add rollup-plugin-resolve-shebang

Imports

resolveShebang

wrong

const resolveShebang = require('rollup-plugin-resolve-shebang')

correct

import { resolveShebang } from 'rollup-plugin-resolve-shebang'

ESM-only; require() will throw ERR_REQUIRE_ESM.

default import
wrong
```
import { default as resolveShebang } from 'rollup-plugin-resolve-shebang'
```
correct
```
import resolveShebangPlugin from 'rollup-plugin-resolve-shebang'
```
The package exports a named export 'resolveShebang' but also supports default import (which resolves to the named export).

TypeScript type

import type { resolveShebang } from 'rollup-plugin-resolve-shebang'

Types are bundled; no separate @types package needed.

Quickstart

Configures Rollup to preserve shebang line from src/cli.js into the output bundle.

import { resolveShebang } from 'rollup-plugin-resolve-shebang';

export default {
  input: 'src/cli.js',
  output: {
    file: 'dist/cli.js',
    format: 'esm',
  },
  plugins: [resolveShebang()],
};