Options

shebang

• Type: string
• Default: Original shebang from source file

Custom shebang to prepend to the output bundle.

replaceShebang({
  shebang: '#!/usr/bin/env node'
})

Template Variables

The shebang option supports template variables that are automatically replaced:

replaceShebang({
  shebang: '#!/usr/bin/env node # ${name} v${version}'
})
// Output: #!/usr/bin/env node # my-cli v1.0.0

Variable	Description
${name}	Package name from package.json
${version}	Package version from package.json

---

skipBackslash

• Type: boolean
• Default: false

Preserve \u005c escape sequences in the output.

replaceShebang({
  skipBackslash: true
})

This is useful when your code contains backslash escape sequences that should be preserved.

---

preserve

• Type: boolean
• Default: false

Preserve the original shebang without modification.

replaceShebang({
  preserve: true
})

When enabled, the plugin will use the exact shebang from the source file, ignoring any custom shebang option.

---

chmod

• Type: boolean
• Default: false

Automatically set executable permission (chmod +x) on output files.

replaceShebang({
  chmod: true
})

This makes the output file directly executable on Unix-like systems.

---

include

• Type: string | string[]
• Default: ['**/*.js', '**/*.ts', '**/*.mjs', '**/*.cjs', '**/*.jsx', '**/*.tsx']

Files to include for shebang processing.

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

Supported Patterns

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

---

exclude

• Type: string | string[]
• Default: ['node_modules/**']

Files to exclude from shebang processing.

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

Supports the same pattern types as include.

---

warnOnMultiple

• Type: boolean
• Default: true

Warn when multiple files have shebangs.

replaceShebang({
  warnOnMultiple: false  // Disable warning
})

When building multiple entry points, the plugin will warn if more than one file contains a shebang, as typically only the main entry point should have one.