{"body":"Add Blog Post about ReactElement Changes in 0.13","parents":["44d91295cb1ad52852cd687ea8182597b969bed3","cd47798c59d7acda50e7c7c2bd51d12f95f50b16"],"patch":"diff --git a\/docs\/_posts\/2015-02-24-streamlining-react-elements.md b\/docs\/_posts\/2015-02-24-streamlining-react-elements.md\nnew file mode 100644\nindex 0000000000..87bc81b5c8\n--- \/dev\/null\n+++ b\/docs\/_posts\/2015-02-24-streamlining-react-elements.md\n@@ -0,0 +1,229 @@\n+---\n+title: \"Streamlining React Elements\"\n+author: Sebastian Markbåge\n+---\n+\n+React v0.13 is right around the corner and so we wanted to discuss some upcoming changes to ReactElement. In particular, we added several warnings to some esoteric use cases of ReactElement. There are no runtime behavior changes for ReactElement - we're adding these warnings in the hope that we can change some behavior in v0.14 if the changes are valuable to the community.\n+\n+If you use React in an idiomatic way, chances are, you’ll never see any of these warnings. In that case, you can skip this blog post. You can just enjoy the benefits! These changes will unlock simplified semantics, better error messages, stack traces and compiler optimizations!\n+\n+## Immutable Props\n+\n+In React 0.12, the props object was mutable. It allows you to do patterns like this:\n+\n+```js\n+var element = ;\n+if (shouldUseFoo) {\n+ element.props.foo = 10;\n+ element.props.bar = true;\n+}\n+```\n+\n+The problem is that we don’t have a convenient way to tell when you’re done mutating.\n+\n+### Problem: Mutating Props You Don’t Own\n+\n+If you mutate something, you destroy the original value. Therefore, there is nothing to diff against. Imaging something like this:\n+\n+```js\n+var element = this.props.child;\n+element.props.count = this.state.count;\n+return element;\n+```\n+\n+You take a ReactElement through `props.child` and mutate its property before rendering it. If this component's state updates, this render function won't actually get a new ReactElement in `props.child`. It will be the same one. You're mutating the same props.\n+\n+You could imagine that this would work. However, this disables the ability for any component to use `shouldComponentUpdate`. It looks like the component never changed because the previous value is always the same as the next one. Since the DOM layer does diffing, this pattern doesn't even work in this case. The change will never propagate down to the DOM except the first time.\n+\n+Additionally, if this element is reused in other places or used to switch back and forth between two modes, then you have all kinds of weird race conditions.\n+\n+It has always been broken to mutate the props of something passed into you. The problem is that we can’t warn you about this special case if you accidentally do this.\n+\n+### Problem: Too Late Validation\n+\n+In React 0.12, we do PropType validation very deep inside React during mounting. This means that by the time you get an error, the debugger stack is long gone. This makes it difficult to find complex issues during debugging. We have to do this since it is fairly common for extra props to be added between the call to React.createElement and the mount time. So the type is incomplete until then.\n+\n+The static analysis in Flow is also impaired by this. There is no convenient place in the code where Flow can determine that the props are finalized.\n+\n+### Solution: Immutable Props\n+\n+Therefore, we would like to be able to freeze the element.props object so that it is immediately immutable at the JSX callsite (or createElement). In React 0.13 we will start warning you if you mutate `element.props` after this point.\n+\n+You can generally refactor these pattern to simply use two different JSX calls:\n+\n+```js\n+if (shouldUseFoo) {\n+ return ;\n+} else {\n+ return ;\n+}\n+```\n+\n+However, if you really need to dynamically build up your props you can just use a temporary object and spread it into JSX:\n+\n+```js\n+var props = { bar: false };\n+if (shouldUseFoo) {\n+ props.foo = 10;\n+ props.bar = true;\n+}\n+return ;\n+```\n+\n+It is still OK to do deep mutations of objects. E.g:\n+\n+```js\n+return ;\n+```\n+\n+In this case it's still ok to mutate the myModel object in state. We recommend that you use fully immutable models. E.g. by using immutable-js. However, we realize that mutable models are still convenient in many cases. Therefore we're only considering shallow freezing the props object that belongs to the ReactElement itself. Not nested objects.\n+\n+### Solution: Early PropType Warnings\n+\n+We will also start warning you for PropTypes at the JSX or createElement callsite. This will help debugging as you’ll have the stack trace right there. Similarly, Flow also validates PropTypes at this callsite.\n+\n+Note: There are valid patterns that clones a ReactElement and adds additional props to it. In that case these additional props needs to be optional.\n+\n+```js\n+var element1 = ; \/\/ extra prop is optional\n+var element2 = React.addons.cloneWithProps(element1, { extra: 'prop' });\n+```\n+\n+## Owner\n+\n+In React each child has both a \"parent\" and an “owner”. The owner is the component that created a ReactElement. I.e. the render method which contains the JSX or createElement callsite.\n+\n+```js\n+class Foo {\n+ render() {\n+ return

<\/div>;\n+ }\n+}\n+```\n+\n+In this example, the owner of the `span` is `Foo` but the parent is the `div`.\n+\n+There is also an undocumented feature called \"context\" that also relies on the concept of an “owner” to pass hidden props down the tree.\n+\n+### Problem: The Semantics are Opaque and Confusing\n+\n+The problem is that these are hidden artifacts attached to the ReactElement. In fact, you probably didn’t even know about it. It silently changes semantics. Take this for example:\n+\n+```js\n+var foo = ;\n+class Component {\n+ render() {\n+ return bar ? : foo;\n+ }\n+}\n+```\n+\n+These two inputs have different owners, therefore React will not keep its state when the conditional switches. There is nothing in the code to indicate that. Similarly, if you use `React.addons.cloneWithProps`, the owner changes.\n+\n+### Problem: Timing Matters\n+\n+The owner is tracked by the currently executing stack. This means that the semantics of a ReactElement varies depending on when it is executed. Take this example:\n+\n+```js\n+class A {\n+ render() {\n+ return {text}<\/span>} \/>;\n+ }\n+}\n+class B {\n+ render() {\n+ return this.props.renderer('foo');\n+ }\n+}\n+```\n+\n+The owner of the `span` is actually `B`, not `A` because of the timing of the callback. This all adds complexity and suffers from similar problems as mutation.\n+\n+### Problem: It Couples JSX to React\n+\n+Have you wondered why JSX depends on React? Couldn’t the transpiler have that built-in to its runtime? The reason you need to have `React.createElement` in scope is because we depend on internal state of React to capture the current \"owner\". Without this, you wouldn’t need to have React in scope.\n+\n+### Solution: Make Context Parent-Based Instead of Owner-Based\n+\n+The first thing we’re doing is warning you if you’re using the \"owner\" feature in a way that relies on it propagating through owners. Instead, we’re planning on propagating it through parents to its children. In almost all cases, this shouldn’t matter. In fact, parent-based contexts is simply a superset.\n+\n+### Solution: Remove the Semantic Implications of Owner\n+\n+It turns out that there are very few cases where owners are actually important part of state-semantics. As a precaution, we’ll warn you if it turns out that the owner is important to determine state. In almost every case this shouldn’t matter. Unless you’re doing some weird optimizations, you shouldn’t see this warning.\n+\n+### Pending: Change the refs Semantics\n+\n+Refs are still based on \"owner\". We haven’t fully solved this special case just yet.\n+\n+In 0.13 we introduced a new callback-refs API that doesn’t suffer from these problems but we’ll keep on a nice declarative alternative to the current semantics for refs. As always, we won’t deprecate something until we’re sure that you’ll have a nice upgrade path.\n+\n+## Keyed Objects as Maps\n+\n+In React 0.12, and earlier, you could use keyed objects to provide an external key to an element or a set. This pattern isn’t actually widely used. It shouldn’t be an issue for most of you.\n+\n+```js\n+
{{ a: , b: }}<\/div>\n+```\n+\n+### Problem: Relies on Enumeration Order\n+\n+The problem with this pattern is that it relies on enumeration order of objects. This is technically unspecified, even though implementations now agree to use insertion order. Except for the special case when numeric keys are used.\n+\n+### Problem: Using Objects as Maps is Bad\n+\n+It is generally accepted that using objects as maps screw up type systems, VM optimizations, compilers etc. It is much better to use a dedicated data structure like ES6 Maps.\n+\n+More importantly, this can have important security implications. For example this has a potential security problem:\n+\n+```js\n+var children = {};\n+items.forEach(item => children[item.title] = );\n+return
{children}<\/div>;\n+```\n+\n+Imagine if `item.title === '__proto__'` for example.\n+\n+### Problem: Can’t be Differentiated from Arbitrary Objects\n+\n+Since these objects can have any keys with almost any value, we can’t differentiate them from a mistake. If you put some random object, we will try our best to traverse it and render it, instead of failing with a helpful warning. In fact, this is one of the few places where you can accidentally get an infinite loop in React.\n+\n+To differentiate ReactElements from one of these objects, we have to tag them with `_isReactElement`. This is another issue preventing us from inlining ReactElements as simple object literals.\n+\n+### Solution: Just use an Array and key={…}\n+\n+Most of the time you can just use an array with keyed ReactElements.\n+\n+```js\n+var children = items.map(item => );\n+
{children}<\/div>\n+```\n+\n+### Solution: React.addons.createFragment\n+\n+However, this is not always possible if you’re trying to add a prefix key to an unknown set (e.g. this.props.children). It is also not always the easiest upgrade path. Therefore, we are adding a helper to `React.addons` called `createFragment()`. This accepts a keyed object and returns an opaque type.\n+\n+```js\n+
{React.addons.createFragment({ a:
, b: this.props.children })}<\/div>\n+```\n+\n+The exact signature of this kind of fragment will be determined later. It will likely be some kind of immutable sequence.\n+\n+Note: This will still not be valid as the direct return value of `render()`. Unfortunately, they still need to be wrapped in a `
` or some other element.\n+\n+## Compiler Optimizations: Unlocked!\n+\n+These changes also unlock several possible compiler optimizations for static content in React 0.14. These optimizations were previously only available to template-based frameworks. They will now also be possible for React code! Both for JSX and `React.createElement\/Factory`*!\n+\n+See these GitHub Issues for a deep dive into compiler optimizations:\n+\n+- [Reuse Constant Value Types](https:\/\/github.com\/facebook\/react\/issues\/3226)\n+- [Tagging ReactElements](https:\/\/github.com\/facebook\/react\/issues\/3227)\n+- [Inline ReactElements](https:\/\/github.com\/facebook\/react\/issues\/3228)\n+\n+\\* If you use the recommended pattern of explicit React.createFactory calls on the consumer side - since they are easily statically analyzed.\n+\n+## Rationale\n+\n+I thought that these changes were particularly important because the mere existence of these patterns means that even components that DON’T use these patterns have to pay the price. There are other problematic patterns such as mutating state, but they’re at least localized to a component subtree so they don’t harm the ecosystem.\n+\n+As always, we’d love to hear your feedback and if you have any trouble upgrading, please let us know.\n","commit":{"authorEmail":"paul@oshannessy.com","authoredAt":"2015-02-24T11:26:55-08:00","shortRevision":"2f20091520","revision":"2f20091520b168e7563a577e87a52d7afef4d879","subject":"Merge pull request #3250 from sebmarkbage\/blogpost","authorName":"Paul O’Shannessy"},"files":[{"status":"A","path":"docs\/_posts\/2015-02-24-streamlining-react-elements.md"}]}

dillon1000/react

Files changed