saqqdy/rollup-plugin-replace-shebang

README

rollup-plugin-replace-shebang

A Rollup plugin that preserves and relocates shebang (#!) to the output bundle.

Background

When building CLI tools with Rollup, the shebang (#!/usr/bin/env node) at the top of your entry file gets removed during bundling. This plugin ensures your shebang is preserved in the final output.

Online Examples

Try the plugin online with StackBlitz:

Example	Description	Link
rollup-v2	Rollup 2.x with template variables	Open in StackBlitz
rollup-v4	Rollup 4.x multi-file project	Open in StackBlitz

Installation

# pnpm
pnpm add -D rollup-plugin-replace-shebang

# npm
npm install -D rollup-plugin-replace-shebang

Usage

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

Options

Option	Type	Default	Description
`shebang`	`string`	Original shebang	Custom shebang to prepend. Supports template variables: `${name}`, `${version}`
`skipBackslash`	`boolean`	`false`	Preserve `\u005c` escape sequences
`preserve`	`boolean`	`false`	Preserve original shebang without modification
`chmod`	`boolean`	`false`	Auto set executable permission (chmod +x) on output files
`include`	`string \| string[]`	`['*/.js', '*/.ts', ...]`	Files to include
`exclude`	`string \| string[]`	`['node_modules/**']`	Files to exclude
`warnOnMultiple`	`boolean`	`true`	Warn when multiple files have shebangs

Template Variables

The shebang option supports template variables:

replaceShebang({
  shebang: '#!/usr/bin/env node # ${name} v${version}'
})
// Output: #!/usr/bin/env node # rollup-plugin-replace-shebang v2.0.0

Include/Exclude Patterns

The plugin supports various glob patterns for filtering files:

Pattern	Example	Matches
Exact match	`src/cli.ts`	Only `src/cli.ts`
Extension match	`*/.ts`	Any `.ts` file in any directory
Prefix match	`src/**`	Any file under `src/`
Directory match	`/node_modules/`	Any file in `node_modules` anywhere
Wildcard match	`src/*.test.ts`	`src/foo.test.ts` but not `src/sub/foo.test.ts`
Plain string	`node_modules`	Any path containing `node_modules`

replaceShebang({
  include: ['src/cli.ts', 'src/bin/*.ts'],
  exclude: ['node_modules/**', '**/*.test.ts']
})

How it works

Transform phase: Extracts and removes shebang from source files
RenderChunk phase: Prepends shebang to the output bundle
WriteBundle phase: Optionally sets executable permissions

Plugin API

The plugin exposes an API for external access:

const plugin = replaceShebang()

// Get shebang for a specific file
plugin.api.getShebang('/path/to/file.js')

// Get all shebangs
plugin.api.getAllShebangs()

Example

Input (src/cli.js):

#!/usr/bin/env node
import { program } from 'commander'

program.parse()

Output (dist/cli.js):

#!/usr/bin/env node
// bundled code...

Requirements

Rollup >= 2.0.0
Node.js >= 12

Feedback

Feel free to submit an Issue for bugs or suggestions.

License

MIT