feature: Support whitelisting mutable props for react-constant-elements (#5307)

packages/babel-plugin-transform-react-constant-elements/README.md

@@ -1,6 +1,9 @@
 # babel-plugin-transform-react-constant-elements
 
-> Treat React JSX elements as value types and hoist them to the highest scope
+> Treat React JSX elements as value types and hoist them to the highest scope.
+
+This plugin can speed up reconciliation and reduce garbage collection pressure by hoisting
+React elements to the highest possible scope, preventing multiple unnecessary reinstantiations.
 
 ## Example
 
@@ -37,6 +40,14 @@ const Hr = () => {
   <div ref={node => this.node = node} />
   ```
 
+- **Mutable Properties**
+
+> See https://github.com/facebook/react/issues/3226 for more on this
+
+  ```js
+  <div width={{width: 100}} />
+  ```
+
 ## Installation
 
 ```sh
@@ -55,6 +66,26 @@ npm install --save-dev babel-plugin-transform-react-constant-elements
 }
 ```
 
+## Options
+
+### `allowMutablePropsOnTags`
+
+`Array<string>`, defaults to `[]`
+
+If you are using a particular library (like react-intl) that uses object properties, and you are sure
+that the element won't modify its own props, you can whitelist the element so that objects are allowed.
+
+This will skip the `Mutable Properties` deopt.
+
+```json
+{
+  "plugins": [
+    ["transform-react-constant-elements", {"allowMutablePropsOnTags": ["FormattedMessage"]}],
+  ]
+}
+
+```
+
 ### Via CLI
 
 ```sh