babel-plugin-transform-replace-object-assign

Replaces Object.assign with a custom implementation that you provide in plugin configuration. This plugin works similarly to the babel-plugin-transform-object-assign plugin except it allows you to provide your own implementation that you would like to replace Object.assign with rather than the _extends helper that Babel uses.

Also, this plugin will import an external package in files where Object.assign is used rather than redeclaring the function in each file (which should help reduce bundle size). This is ultimately what babel-plugin-transform-runtime does for you when using the _extends helper.

The implementation you configure is specified as a npm package dependency.

⚠️ Important note on the use of this project:

Most likely you do not and should not use this plugin! I initially wrote this plugin due to a bug in Chrome where key order was not gaurenteed to be correct for objects mutated with Object.assign (the issue is also described at sindresorhus/object-assign#22).

While the bug did not cause problems for most projects, it did causes problems for a project I was helping maintain (Material-UI). We heavily used Object.assign to merge style definitions that were defined in javascript objects. Since key order is important when defining CSS style rules, the Object.assign implementation built into Chrome caused many style related bugs. This plugin allowed us to completely replace all uses of Object.assign within our source code with an implementation that did not break in Chrome (with the expectation that we would stop using this plugin when the bug was fixed and rolled out to a majority of Chrome users).

The bug in Chrome has been fixed for quite some time now (it was fixed in Chrome 49), so this plugin is no longer necessary for the purpose it was originally created for. We have also stopped using this plugin for Material-UI. Please carefully consider the necessity and implications of replacing all of your Object.assign calls before using this plugin. If you are not sure if you need this, feel free to open an issue to discuss it.

Usage

Installation

# Install the plugin
$ npm install --save-dev babel-plugin-transform-replace-object-assign

# Install an assign implementation
$ npm install object-assign

Configure

When you provide the plugin, use the moduleSpecifier option to specify which package you would like imported and used when replacing Object.assign.

.babelrc

{
  "plugins": [
    ["transform-replace-object-assign", { "moduleSpecifier": "object-assign" }]
  ]
}

To use defaults (which is the same as above):

{
  "plugins": ["transform-replace-object-assign"]
}

Result

In

Object.assign(a, b);

Out

import _objectAssign from 'object-assign';

_objectAssign(a, b);

Contributors

Thanks goes to these wonderful people (emoji key):

Neil Gabbadon 💻 📖	Ivan Nikolić 🐛	Jordan Harband 🤔	Jayden Seric 💻 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

Changelog

Unreleased changes

2.0.0

• Official support for stable babel v7! :tada:

• Chores (via #8):

  • Replaced deprecated @babel/preset-es2015 with @babel/preset-env
  • Updated babel related dependencies to stable Babel v7 release
  • Updated other development dependencies (mocha, all-contributors-cli)

2.0.0-beta.0

• Via #3:
  • Updated dependencies.
  • New plugin implementation for Babel v7.
  • Use @babel/helper-module-imports so the output is either ESM or CJS depending if sourceType is module or script, fixing #1.
  • Added @babel/core peer dependency, as Babel does for official plugins.
  • Disabled and ignored package-lock.json.
  • Replaced lodash.assign in readme examples with object-assign to demo defaults.
  • New way to register Babel for Mocha tests.

1.0.0

• The plugin configuration is now optional. If no configuration is provided, the Object.assign implementation will be replaced with object-assign.

  This will replace Object.assign with object-assign:

  {
    "plugins": [["transform-replace-object-assign"]]
  }

• Breaking change: The plugin configuration no longer supports passing a string module name. If you want to provide a custom Object.assign implementation, you must provide an object config with the name of the module specified in the moduleSpecifier key.

  This:

  {
    "plugins": [["transform-replace-object-assign", "custom-module"]]
  }

  Should be changed to this:

  {
    "plugins": [
      [
        "transform-replace-object-assign",
        { "moduleSpecifier": "custom-module" }
      ]
    ]
  }

Thanks to @jaydenseric for proposing these changes in preparation for babel v7.

0.2.1

There were no code changes in this release. This patch fixed some documentation errors in README.md so that it would show in the npm registry.

0.2.0

First release of this plugin! :smile:

View the README.md to learn how it works!