rollup-plugin-comment-swap

A powerful and flexible Rollup plugin for injecting values and code into bundled files.

Comment Swap 101

‘Comment Swap’ currently supports:

• /* block comments in JavaScript and CSS */
• <!-- HTML comments -->

Literal Comment Swap

A single literal will be replaced after a block comment which ends with an equals sign ‘=’.
In the same way, a single literal will be replaced before a block which begins with an equals sign ‘=’.

Any JavaScript literal can be replaced by any other JavaScript literal.
Typically you will replace like-for-like, for example a string for another string:

const hero = /* 'Batman' =*/ 'Bruce Wayne';
const villain = 'Oswald Cobblepot' /*= 'The Penguin' */;

// Source code logs 'Bruce Wayne', bundled code logs 'Batman':
console.log(hero);

// Source code logs 'Oswald Cobblepot', bundled code logs 'The Penguin':
console.log(villain);

In HTML, everything is treated as a string:

<dl>

  <!-- Source HTML says 'Bruce Wayne', bundled HTML says 'Batman': -->
  <dt>Hero</dt>
  <dd><!-- Batman =-->Bruce Wayne</dd>

  <!-- Source HTML says 'Oswald Cobblepot', bundled HTML says 'The Penguin': -->
  <dt>Villain</dt>
  <dd>Oswald Cobblepot<!--= The Penguin --></dd>

</dl>

Note that the function name greetBruceWayne is replaced by greetBatman, so the bundled code will call greetBatman('9:30am'):

import { greetBruceWayne /*= greetBatman */ } from 'greetings';

// Source code logs 'Morning Bruce!', bundled code logs 'Morning Batman!':
console.log(/* greetBatman =*/ greetBruceWayne('9:30am'));

Variable Comment Swap

A single variable will be replaced after a block comment which ends with a dollar sign ‘$’.
In the same way, a single variable will be replaced before a block which begins with a dollar sign ‘$’.

These variables are copied from the $ object — see Usage, below.

@TODO example

In HTML:

@TODO example

Literal Ternary Comment Swap

@TODO describe

Variable Ternary Comment Swap

@TODO describe

Whitespace

@TODO discuss when and where whitespace is ignored

Requirements

This plugin requires an LTS Node version (v14.0.0+) and Rollup v1.20.0+.

Install

Using npm:

npm install rollup-plugin-comment-swap --save-dev

Usage

Create a rollup.config.js configuration file and import the plugin:

const commentSwap = require('rollup-plugin-comment-swap');

module.exports = {
  input: 'src/index.js',
  output: {
    dir: 'output',
    format: 'cjs'
  },
  plugins: [commentSwap({
    $: {
      hero: 'Batman!',
      hasThemeTune: true,
    },
  })]
};

Create an accompanying file src/index.js, containing some Comment Swaps:

// Literal Comment Swap, using `=*/`
console.log(/* 1234 =*/ 'Oh, hello');

// Literal Ternary Comment Swap, using `?*/` and `/*=`
console.log(/* hasThemeTune ?*/ '.'/*= 'na ' */.repeat(4));

// Variable Comment Swap, using `$*/`
console.log(/* hero $*/ 'Bruce Wayne.');

Node ignores your Comment Swaps in the original source code:

node src/index.js
Oh hello
....
Bruce Wayne.

Then call rollup either via the CLI or the API. Rollup generates the bundle output/index.js:

console.log(1234);
console.log('na '.repeat(4));
console.log('Batman!');

In the bundled file, your Comment Swaps have been combined with the $ object passed to commentSwap() in rollup.config.js:

node output/index.js
1234
na na na na
Batman!

Options

exclude @TODO

Type: String | Array[...String]
Default: null

A picomatch pattern, or array of patterns, which specifies the files in the build the plugin should ignore. By default no files are ignored.

include @TODO

Type: String | Array[...String]
Default: null

A picomatch pattern, or array of patterns, which specifies the files in the build the plugin should operate on. By default all files are targeted.

quick @TODO

Type: Boolean
Default: true

If true, rollup-plugin-comment-swap will process source code using a ‘quick and dirty’ string searching algorithm, which ignores code context. Any sequence of characters which looks like a Comment Swap will be processed, even inside strings or inside other comments. Additionally, the quick algorithm may not correctly recognise the value being replaced. @TODO elaborate with examples

If false, rollup-plugin-comment-swap will parse the source code into an [https://en.wikipedia.org/wiki/Abstract_syntax_tree](abstract syntax tree) first, so that only genuine comments are processed. Additionally, the value being replaced should always be recognised.

$

Type: Object
Default: null

An optional object, containing variables which Comment Swap can access.
@TODO describe in more detail