Rollup Plugin CLI

0.1.5 verified Mon Apr 27 auth: no javascript

A rollup plugin that prepends a hashbang (shebang) line to bundled JavaScript files for CLI use. The current stable version is 0.1.5. The plugin is minimalist and has no notable release cadence. It differentiates itself by being a straightforward, small plugin that simply adds a hashbang to the output bundle, allowing Rollup to generate executable CLI scripts. It supports a configurable hashbang via options and has no dependencies. It is only useful for Node.js CLI projects built with Rollup and should not be used for browser bundles.

Common errors

error Error: Cannot find module 'rollup-plugin-cli' ↓

cause The package is not installed or the import path is incorrect (e.g., missing file extension).

fix

Run 'npm install rollup-plugin-cli' and use 'import cli from 'rollup-plugin-cli'' (no extension).

error TypeError: cli is not a function ↓

cause Forgetting to call the exported function in the plugins array.

fix

Use 'cli()' with parentheses, e.g., 'plugins: [ cli() ]'.

error Hashbang added to wrong output ↓

cause When using multiple output formats or code splitting, the hashbang is only added to the first output chunk.

fix

Structure your Rollup config so that the CLI entry point is the sole input or use a different plugin to add hashbangs per chunk.

Warnings

gotcha The plugin only prepends the hashbang to the first output chunk. If using code-splitting or multiple outputs, only the first entry point chunk gets the hashbang. ↓

fix Ensure your CLI script is the first entry point or combine outputs manually.

gotcha The hashbang line is added as text; there is no validation the resulting file will be executable. You must still set executable permissions (chmod +x) on the output file. ↓

fix After bundling, run chmod +x on the output file.

gotcha The plugin does not handle Windows line endings or carriage returns. On Windows, the hashbang may not work as expected. ↓

fix Use a cross-platform tool like 'pkg' or include a post-build step to adjust line endings.

Install

npm install rollup-plugin-cli

yarn add rollup-plugin-cli

pnpm add rollup-plugin-cli

Imports

default

wrong

const cli = require('rollup-plugin-cli')

correct

import cli from 'rollup-plugin-cli'

ESM-only; no CommonJS support. Use import syntax.

plugin function
wrong
```
plugins: [ cli ]
```
correct
```
plugins: [ cli() ]
```
Must be called as a function (with or without options) in the plugins array.
TypeScript import
wrong
```
import * as cli from 'rollup-plugin-cli'
```
correct
```
import cli from 'rollup-plugin-cli'
```
The plugin has no type definitions; use with @rollup/plugin-typescript or similar.

Quickstart

Minimal Rollup configuration that adds a Node.js hashbang to the output bundle.

// rollup.config.js
import cli from 'rollup-plugin-cli';

export default {
  input: 'src/index.js',
  output: {
    file: 'bin/cli.js',
    format: 'cjs'
  },
  plugins: [
    cli() // adds #!/usr/bin/env node
  ]
};