babel-plugin-transform-builtin-classes

0.6.1 verified Sat Apr 25 auth: no javascript maintenance

Babel plugin (v0.6.1) that fixes extending built-in classes like Array, Error, HTMLElement, etc., which are notoriously broken in transpiled ES2015 classes. It patches the prototype chain so that instances created via `new MySubclass()` properly inherit from the subclass and its constructor. Requires `babel-plugin-transform-es2015-classes` as a prerequisite. Key differentiator: handles multiple globals, has a `logIfPatched` option, and works with Rollup (inverted plugin order). No known active development; last release was in 2017. Compatible with IE11+ and uses `Object.setPrototypeOf` or `__proto__` as fallback.

Common errors

error TypeError: Cannot set prototype of #<MyArray> which only has a getter for 'prototype' ↓

cause Attempting to extend a built-in that is not in the globals list, so the plugin did not patch the prototype chain.

fix

Add the built-in to the globals option: e.g., { "globals": ["Array"] }.

error MyArray is not a constructor ↓

cause The plugin is applied before transform-es2015-classes, leaving the class declaration untranspiled in older Babel.

fix

Reorder plugins: ensure transform-es2015-classes comes before transform-builtin-classes (or after for Rollup).

error ReferenceError: HTMLElement is not defined ↓

cause HTMLElement global is missing in Node.js environment; plugin only works in browser contexts.

fix

Remove 'HTMLElement' from globals when running in Node, or conditionally configure.

error console.warn: ✔ builtin extends patched (too many times) ↓

cause The logIfPatched option is enabled and logs for every class that extends a built-in, causing console noise.

fix

Set logIfPatched: false or remove the option.

Warnings

gotcha Plugin requires babel-plugin-transform-es2015-classes (or preset es2015) to be present; otherwise no transformation occurs. ↓

fix Add 'babel-plugin-transform-es2015-classes' to plugins (or use babel-preset-es2015).

gotcha Plugin must be applied _after_ transform-es2015-classes in Babel, but _before_ it in Rollup. Incorrect order breaks subclassing. ↓

fix For Babel: order as ["transform-es2015-classes", ["transform-builtin-classes",...]]. For Rollup: invert order.

deprecated No updates since 2017; may be incompatible with Babel 7+ and modern JavaScript engines that natively support subclassing built-ins. ↓

fix Consider using @babel/plugin-proposal-class-properties and modern Babel presets, or switch to native ES2015+ environments.

gotcha Does not support Internet Explorer 10 or below. Requires Object.setPrototypeOf or __proto__. ↓

fix Ensure target browsers include IE11+ or polyfill Object.setPrototypeOf.

gotcha The 'globals' option default is an empty array; without specifying globals, no classes are transformed. ↓

fix Always provide a globals array: e.g., ["Array", "Error"].

Install

npm install babel-plugin-transform-builtin-classes

yarn add babel-plugin-transform-builtin-classes

pnpm add babel-plugin-transform-builtin-classes

Imports

default (plugin)

wrong

import transformBuiltinClasses from 'babel-plugin-transform-builtin-classes'

correct

module.exports = { plugins: [["babel-plugin-transform-builtin-classes", { globals: ["Array"] }]] }

This is a Babel plugin, not a runtime import. It's used in .babelrc or programmatically as a plugin entry.

globals option

wrong

["transform-builtin-classes", { "builtins": ["Array"] }]

correct

["transform-builtin-classes", { "globals": ["Array", "Error", "HTMLElement"] }]

Option key is 'globals', not 'builtins' or 'classes'. Must be an array of global constructor names.

rollup usage

wrong

plugins: ['transform-es2015-classes', ['transform-builtin-classes', { globals: ['HTMLElement'] }]]

correct

plugins: [['transform-builtin-classes', { globals: ['HTMLElement'] }], 'transform-es2015-classes']

In Rollup, the order must be inverted: builtin-classes before es2015-classes, contrary to Babel standalone.

Quickstart

Enables the plugin in Babel 6 configuration, targeting Array, Error, and HTMLElement globals. Shows a simple subclass of Array and verifies instance relationships.

// .babelrc
{
  "plugins": [
    "babel-plugin-transform-es2015-classes",
    ["babel-plugin-transform-builtin-classes", {
      "globals": ["Array", "Error", "HTMLElement"],
      "logIfPatched": true
    }]
  ]
}

// source.js
class MyArray extends Array {
  first() { return this[0]; }
}
const arr = new MyArray(1, 2, 3);
console.log(arr instanceof MyArray); // true
console.log(arr.first()); // 1