babel-plugin-annotate-pure-calls

0.5.0 verified Sat Apr 25 auth: no javascript

Babel plugin (v0.5.0) that automatically inserts #__PURE__ annotations on top-level call expressions and new expressions in assignment contexts, enabling UglifyJS and Terser to perform dead code elimination for improved bundle sizes. Targeted at libraries where top-level calls are generally side-effect-free, but may break code if misapplied. Current stable version is 0.5.0 with Node >= 18 and peer dependency on @babel/core ^7.0.0. The plugin is actively maintained but the API is simple and stable. Compared to alternatives like 'annotate-pure-call-in-variable-declarator', this plugin covers broader contexts (IIFEs, nested IIFEs) and is more widely adopted.

Common errors

error Cannot find module 'babel-plugin-annotate-pure-calls' ↓

cause Plugin not installed or installed globally instead of locally.

fix

Run npm install --save-dev babel-plugin-annotate-pure-calls in the project directory.

error Unmet peer dependency @babel/core@^7.0.0 ↓

cause Missing or incompatible version of @babel/core.

fix

Install @babel/core: npm install --save-dev @babel/core (ensure version ^7.0.0).

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

cause Plugin is not a function; imported incorrectly when using programmatic API.

fix

Use require('babel-plugin-annotate-pure-calls') instead of a string in Babel transform options.

Warnings

gotcha Plugin may annotate impure top-level calls (e.g., calls with side effects) as pure, leading to broken code after minification. ↓

fix Use only for libraries where top-level calls are predominantly side-effect-free; manually review or use additional linting.

gotcha Calls not in an assignment context (e.g., pure statements like mutate({})) are NOT annotated, which is correct but may be surprising for those expecting all top-level calls to be annotated. ↓

fix Understand the plugin's scope: only variable declarations and assignment expressions at top level are annotated.

gotcha The plugin requires Node >= 18 as of version 0.5.0; older versions may not work. ↓

fix Upgrade Node to version 18 or later, or use an older version of the plugin (if available).

Install

npm install babel-plugin-annotate-pure-calls

yarn add babel-plugin-annotate-pure-calls

pnpm add babel-plugin-annotate-pure-calls

Imports

plugin
wrong
```
plugins: ['babel-plugin-annotate-pure-calls']
```
correct
```
// In .babelrc or babel.config.js: plugins: ['annotate-pure-calls']
```
The plugin name is 'annotate-pure-calls' when used in Babel config; the full npm package name is optional.

default

wrong

import annotatePureCalls from 'babel-plugin-annotate-pure-calls';

correct

const annotatePureCalls = require('babel-plugin-annotate-pure-calls');

The plugin is exported as CommonJS; ES import may not work depending on bundler configuration.

annotate-pure-calls

wrong

babel.transform(code, { plugins: ['annotate-pure-calls'] });

correct

// programmatic usage:
const babel = require('@babel/core');
babel.transform(code, { plugins: [require('babel-plugin-annotate-pure-calls')] });

When using programmatic API, you must pass the plugin object, not a string. Strings only work in config files.

Quickstart

Shows installation, configuration, and a simple example of the plugin annotating a pure call.

// Install: npm install --save-dev babel-plugin-annotate-pure-calls
// .babelrc
{
  "plugins": ["annotate-pure-calls"]
}

// Input: top-level call
var inc = add(1);

// Output: annotated with #__PURE__
var inc = /*#__PURE__*/add(1);

// Note: Only top-level calls in assignment contexts are annotated; calls like mutate({}) remain unannotated.