rollup-plugin-your-function

0.5.3 verified Mon Apr 27 auth: no javascript

A Rollup plugin that accepts a user-defined function to manipulate build output. Version 0.5.3, stable with occasional updates. Provides a minimal API for custom source transformations without learning plugin-specific DSLs. Unlike replace, string-replace, or regex plugins, it allows arbitrary JavaScript logic including async operations, conditional transformations based on file ID, and custom sourcemap generation. Supports both build and output plugin modes with include/exclude minimatch filtering. No external dependencies beyond Rollup peer.

Common errors

error TypeError: Cannot read properties of undefined (reading 'replace') ↓

cause The fn function is called with source as undefined because the plugin is not properly registered or the file is excluded.

fix

Check include/exclude patterns; ensure the file matches include and not exclude. Verify the plugin is added to the plugins array.

error Error: The plugin 'yourFunction' returned an unsupported value. Expected a string, an array, or an object with code property. ↓

cause The fn function returned something other than a string, [code, map], or {code, map}.

fix

Ensure the return value is one of the supported formats. Example: return processedSource; or return [processedSource, map]; or return { code: processedSource, map: map }.

error TypeError: yourFunction is not a function ↓

cause Import statement is incorrect; likely using default import instead of named import.

fix

Use named import: import { yourFunction } from 'rollup-plugin-your-function'. In CommonJS: const { yourFunction } = require('rollup-plugin-your-function').

Warnings

gotcha Output plugin mode requires calling the returned function ↓

fix When using output:true, assign the result of yourFunction() to a variable and call it as a function in output.plugins: const myPlugin = yourFunction({output:true, name:'my', fn:...}); output: { plugins: [myPlugin()] }

gotcha Return value format must be exactly string, [code, map?], or {code, map?} ↓

fix Ensure your function returns either a string, an array with code as first element (optional map as second), or an object with code property (optional map property). Returning null or undefined will cause errors.

deprecated No breaking changes recorded; minor API stability ↓

fix No action needed.

Install

npm install rollup-plugin-your-function

yarn add rollup-plugin-your-function

pnpm add rollup-plugin-your-function

Imports

yourFunction
wrong
```
import yourFunction from 'rollup-plugin-your-function'
```
correct
```
import { yourFunction } from 'rollup-plugin-your-function'
```
Default export does not exist; the library exports a named export 'yourFunction'. CommonJS: const { yourFunction } = require('rollup-plugin-your-function').

yourFunction (output plugin mode)

wrong

yourFunction({ output: true, fn: ... }) directly in output.plugins (missing function call wrapper)

correct

const myPlugin = yourFunction({ output: true, name: 'myPlugin', fn: ... }); then use myPlugin() in output.plugins

When using as output plugin, yourFunction returns a plugin generator that must be called to get the actual plugin object.

yourFunctionOptions.fn

wrong

yourFunction({ fn: async (source) => { return code; } }) missing await in config

correct

yourFunction({ fn: (source) => { return code; } })

The fn can be sync or async; Rollup handles promises. No need to await in the config.

Quickstart

Basic usage: transform build files by replacing console.log calls and appending a comment using a custom function.

// rollup.config.js
import { yourFunction } from 'rollup-plugin-your-function';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    yourFunction({
      include: '**/*.js',
      exclude: 'node_modules/**',
      fn: (source, options) => {
        // Replace 'console.log' with 'console.info'
        let code = source.replace(/console\.log/g, 'console.info');
        // Append a comment
        code += '\n// Transformed by rollup-plugin-your-function';
        return code;
      }
    })
  ]
};

// Then run: rollup -c