@babel/plugin-transform-react-pure-annotations

A Babel plugin that automatically adds /*#__PURE__*/ annotations to specific React method calls to enable better tree shaking optimization by bundlers like Webpack and Rollup. The plugin identifies React method calls whether they're imported as named imports or accessed through default/namespace imports, and marks them as pure functions that can be safely eliminated during dead code elimination if their results are unused.

Package Information

• Package Name: @babel/plugin-transform-react-pure-annotations
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev @babel/plugin-transform-react-pure-annotations

Core Imports

This is a Babel plugin, so it's typically configured in your Babel configuration rather than imported directly:

{
  "plugins": ["@babel/plugin-transform-react-pure-annotations"]
}

For programmatic usage with Babel API:

import transformReactPureAnnotations from "@babel/plugin-transform-react-pure-annotations";

The plugin internally uses these imports (for plugin development reference):

import { declare } from "@babel/helper-plugin-utils";
import annotateAsPure from "@babel/helper-annotate-as-pure";
import { types as t, type NodePath } from "@babel/core";

Basic Usage

Babel Configuration

Add the plugin to your Babel configuration file (.babelrc, babel.config.js, or package.json):

{
  "plugins": ["@babel/plugin-transform-react-pure-annotations"]
}

With Other Babel Plugins

{
  "presets": ["@babel/preset-react"],
  "plugins": ["@babel/plugin-transform-react-pure-annotations"]
}

Programmatic Usage

import { transform } from "@babel/core";
import transformReactPureAnnotations from "@babel/plugin-transform-react-pure-annotations";

const result = transform(code, {
  plugins: [transformReactPureAnnotations]
});

Input/Output Example

Input:

import React from 'react';
import { createContext, memo } from 'react';
import * as ReactAll from 'react';
import ReactDOM from 'react-dom';

const element = React.createElement('div');
const context = createContext();
const memoized = memo(Component);
const namespaced = ReactAll.forwardRef(Component);
const portal = ReactDOM.createPortal(element, container);

Output:

import React from 'react';
import { createContext, memo } from 'react';
import * as ReactAll from 'react';
import ReactDOM from 'react-dom';

const element = /*#__PURE__*/React.createElement('div');
const context = /*#__PURE__*/createContext();
const memoized = /*#__PURE__*/memo(Component);
const namespaced = /*#__PURE__*/ReactAll.forwardRef(Component);
const portal = /*#__PURE__*/ReactDOM.createPortal(element, container);

Capabilities

Main Plugin Export

The plugin exports a default Babel plugin created using the declare helper from @babel/helper-plugin-utils.

/**
 * A Babel plugin that adds pure annotations to React method calls
 * Created using declare() from @babel/helper-plugin-utils
 */
declare const plugin: BabelPlugin;
export default plugin;

interface BabelPlugin {
  name: string;
  visitor: {
    CallExpression(path: NodePath<t.CallExpression>): void;
  };
}

type NodePath<T> = import('@babel/core').NodePath<T>;
type t = typeof import('@babel/core').types;

Internal Implementation

The plugin implementation includes a visitor pattern that processes CallExpression nodes in the AST. It uses an internal helper function to identify React method calls:

/**
 * Internal function that determines if a call expression is a React method call
 * that should be annotated as pure. Handles both named imports and member expressions.
 * @param path - Babel NodePath for the CallExpression
 * @returns boolean indicating if the call should be marked as pure
 */
function isReactCall(path: NodePath<t.CallExpression>): boolean;

The plugin processes two types of call patterns:

1. Named imports: createContext() from import { createContext } from 'react'
2. Member expressions: React.createContext() from import React from 'react' or import * as React from 'react'

The plugin uses an internal PURE_CALLS mapping to define exactly which methods should be annotated as pure.

Supported React Methods

The plugin automatically annotates calls to the following React methods (as defined in the internal PURE_CALLS constant):

From 'react' module:

• cloneElement: Creates a clone of a React element
• createContext: Creates a React context object
• createElement: Creates a React element
• createFactory: Creates a factory function for React elements (deprecated)
• createRef: Creates a React ref object
• forwardRef: Creates a React component that forwards refs
• isValidElement: Checks if an object is a valid React element
• memo: Creates a memoized React component
• lazy: Creates a lazy-loaded React component

From 'react-dom' module:

• createPortal: Creates a portal to render children into a different DOM subtree

Import Pattern Support

The plugin supports all common React import patterns:

// Named imports
import { createElement, memo } from 'react';
createElement('div'); // ✓ Will be annotated
memo(Component);      // ✓ Will be annotated

// Default import
import React from 'react';
React.createElement('div'); // ✓ Will be annotated
React.memo(Component);      // ✓ Will be annotated

// Namespace import
import * as React from 'react';
React.createElement('div'); // ✓ Will be annotated
React.memo(Component);      // ✓ Will be annotated

// Mixed imports
import React, { memo } from 'react';
React.createElement('div'); // ✓ Will be annotated
memo(Component);            // ✓ Will be annotated

Configuration

This plugin requires no configuration options. It works automatically once added to your Babel configuration.

Requirements

• Babel Version: Requires Babel 7.0.0 or higher
• Node.js: Requires Node.js 6.9.0 or higher
• Peer Dependencies: @babel/core ^7.0.0-0

Dependencies

The plugin uses the following Babel helpers:

• @babel/helper-annotate-as-pure: Adds the pure annotations to AST nodes
• @babel/helper-plugin-utils: Provides the declare function for plugin creation

Benefits

• Tree Shaking: Enables bundlers to eliminate unused React components and method calls
• Bundle Size Reduction: Reduces final bundle size by removing dead code
• Zero Configuration: Works automatically without any setup
• Universal Compatibility: Supports all React import patterns
• Type Safety: Written in TypeScript with full type definitions