babel-plugin-transform-proxy-compat

0.22.4 verified Sat Apr 25 auth: no javascript maintenance

Babel plugin that rewrites property lookups, assignments, deletions, function invocations, 'in' statements, and 'for...in' loops to use function calls from a proxy-compat library, enabling Proxy semantics in environments like IE 11 that lack native Proxy support. Current stable version is 0.22.4, with maintenance-level releases. Key differentiator: allows using modern Proxy-based reactivity or interceptors while targeting legacy browsers without polyfilling Proxy itself. Typically paired with libraries like `proxy-compat` that provide the runtime helper functions.

Common errors

error Error: Could not find module 'proxy-compat' ↓

cause The runtime dependency 'proxy-compat' is not installed.

fix

Run: npm install proxy-compat --save

error TypeError: callKey is not a function ↓

cause Using 'independent' mode but importing the wrong export.

fix

Change import to: import callKey from 'proxy-compat/callKey'; (not from 'proxy-compat')

error TypeError: ProxyCompat.callKey is undefined ↓

cause Using CommonJS require without the correct import pattern.

fix

Use: const ProxyCompat = require('proxy-compat'); (no .default)

Warnings

gotcha Plugin rewrites ALL object property access, assignment, deletion, and 'in'/'for...in' expressions, even if not related to a Proxy. This can cause significant code bloat and performance degradation. ↓

fix Use /* proxy-compat-disable */ comment at top of files that are performance-sensitive and do not use Proxy.

breaking Option 'resolveProxyCompat' changed from accepting a string to an object with module/global/independent properties (v0.16+). ↓

fix Update config to use { module: '...' } or { global: '...' } instead of just a string.

deprecated The 'polyfill' option was removed in favor of 'resolveProxyCompat' (v0.10+). ↓

fix Use resolveProxyCompat with module or global sub-option.

gotcha When using 'global' mode, the global variable must be defined before the transformed code runs. The plugin does not inject a polyfill. ↓

fix Ensure a global variable (e.g., window.MyProxyCompat) is defined via a script tag or other means.

gotcha Plugin does not transform property access on literals (e.g., 'abc'.length) or built-in objects like Array.prototype. Only object property access is transformed. ↓

fix Be aware that some property accesses may not be rewritten; test thoroughly.

Install

npm install babel-plugin-transform-proxy-compat

yarn add babel-plugin-transform-proxy-compat

pnpm add babel-plugin-transform-proxy-compat

Imports

babel-plugin-transform-proxy-compat

wrong

const plugin = require('babel-plugin-transform-proxy-compat');

correct

import plugin from 'babel-plugin-transform-proxy-compat';

CommonJS require works; this plugin is not ESM-only.

callKey
wrong
```
import callKey from 'proxy-compat';
```
correct
```
import { callKey } from 'proxy-compat';
```
callKey is a named export from proxy-compat; default export is the whole module.
ProxyCompat
wrong
```
const ProxyCompat = require('proxy-compat').default;
```
correct
```
import ProxyCompat from 'proxy-compat';
```
CommonJS users should use const ProxyCompat = require('proxy-compat'); (no .default)

Quickstart

Configures Babel to transform Proxy operations to use proxy-compat runtime for IE 11 compatibility.

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-transform-proxy-compat', {
      resolveProxyCompat: {
        module: 'proxy-compat'
      }
    }]
  ]
};

// source.js
const obj = new Proxy({}, {
  get(target, prop) {
    return prop in target ? target[prop] : 42;
  }
});
console.log(obj.foo); // becomes: console.log(callKey(obj, 'foo'));