rollup-plugin-insert

1.3.2 verified Mon Apr 27 auth: no javascript maintenance

A Rollup plugin for string mutation operations on file contents: append, prepend, wrap, and custom transforms. Current stable version is 1.3.2 (last released March 2021). The plugin supports MagicString for source map-aware transformations, ships TypeScript types, and operates in maintenance mode with no recent activity. Key differentiators include separate importable functions, optional source map support, and file filtering via include/exclude patterns. Unlike general-purpose plugins like rollup-plugin-string, it focuses specifically on string insertion/wrapping transforms.

Common errors

error TypeError: insert.append is not a function ↓

cause Using default import instead of named import; default import is an object with methods.

fix

Use named imports: import { append } from 'rollup-plugin-insert'

error Error: Could not resolve 'rollup-plugin-insert' ↓

cause Plugin not installed or missing from dependencies.

fix

Run npm install --save-dev rollup-plugin-insert

error TypeError: Cannot read property 'transform' of undefined ↓

cause Accessing .transform on the default export incorrectly.

fix

Use named import: import { transform } from 'rollup-plugin-insert'

Warnings

gotcha Transform callback must return a string or MagicString; returning undefined silently removes output. ↓

fix Always return a value from transform callback, e.g., code or magicString.toString()

deprecated The plugin has not been updated since 2021; relies on older Rollup versions (<4). ↓

fix Consider migrating to alternative plugins like rollup-plugin-string or @rollup/plugin-replace if using Rollup 4+.

gotcha Source map is enabled by default and may cause memory issues with large files. ↓

fix Explicitly set { sourceMap: false } in the options object if not needed.

gotcha Include/exclude patterns are not applied to the options object but as a separate argument. ↓

fix Use correct signature: append('string', { include: '**/*.txt' })

Install

npm install rollup-plugin-insert

yarn add rollup-plugin-insert

pnpm add rollup-plugin-insert

Imports

append

wrong

import append from 'rollup-plugin-insert'

correct

import { append } from 'rollup-plugin-insert'

append is a named export, not a default export.

prepend

wrong

const prepend = require('rollup-plugin-insert').prepend

correct

import { prepend } from 'rollup-plugin-insert'

CommonJS require() works but ESM with named import is recommended.

wrap
```
import { wrap } from 'rollup-plugin-insert'
```
wrap is a named export; no common wrong usage.

transform

wrong

import insert from 'rollup-plugin-insert'; const transform = insert.transform

correct

import { transform } from 'rollup-plugin-insert'

Default import exists but not recommended; use named imports for tree-shaking.

Quickstart

Shows usage of all four main functions (append, prepend, wrap, transform) in a Rollup config.

// rollup.config.js
import { append, prepend, wrap, transform } from 'rollup-plugin-insert';

export default {
  input: 'src/main.js',
  output: { file: 'dist/bundle.js', format: 'iife' },
  plugins: [
    append('\n// Appended footer'),
    prepend('// Prepended header\n'),
    wrap('/* start */', '/* end */'),
    transform((magicString, code, id) => code.toUpperCase()),
  ],
};