React v0.14 Beta 1

July 3, 2015 by Ben Alpert

This week, many people in the React community are at ReactEurope in the beautiful (and very warm) city of Paris, the second React conference that's been held to date. At our last conference, we released the first beta of React 0.13, and we figured we'd do the same today with our first beta of React 0.14, giving you something to play with if you're not at the conference or you're looking for something to do on the way home.

With React 0.14, we're continuing to let React mature and to make minor changes as the APIs continue to settle down. I'll talk only about the two largest changes in this blog post; when we publish the final release we'll be sure to update all of our documentation and include a full changelog.

You can install the new beta with npm install react@0.14.0-beta1 and npm install react-dom@0.14.0-beta1. As mentioned in Deprecating react-tools, we're no longer updating the react-tools package so this release doesn't include a new version of it. Please try the new version out and let us know what you think, and please do file issues on our GitHub repo if you run into any problems.

Two Packages #

As we look at packages like react-native, react-art, react-canvas, and react-three, it's become clear that the beauty and essence of React has nothing to do with browsers or the DOM.

We think the true foundations of React are simply ideas of components and elements: being able to describe what you want to render in a declarative way. These are the pieces shared by all of these different packages. The parts of React specific to certain rendering targets aren't usually what we think of when we think of React. As one example, DOM diffing currently enables us to build React for the browser and make it fast enough to be useful, but if the DOM didn't have a stateful, imperative API, we might not need diffing at all.

To make this more clear and to make it easier to build more environments that React can render to, we're splitting the main react package into two: react and react-dom.

The react package contains React.createElement, React.createClass and React.Component, React.PropTypes, React.Children, and the other helpers related to elements and component classes. We think of these as the isomorphic or universal helpers that you need to build components.

The react-dom package contains ReactDOM.render, ReactDOM.unmountComponentAtNode, and ReactDOM.findDOMNode, and in react-dom/server we have server-side rendering support with ReactDOMServer.renderToString and ReactDOMServer.renderToStaticMarkup.

var React = require('react');
var ReactDOM = require('react-dom');

var MyComponent = React.createClass({
  render: function() {
    return <div>Hello World</div>;

ReactDOM.render(<MyComponent />, node);

We anticipate that most components will need to depend only on the react package, which is lightweight and doesn't include any of the actual rendering logic. To start, we expect people to render DOM-based components with our react-dom package, but there's nothing stopping someone from diving deep on performance and writing a awesome-faster-react-dom package which can render the exact same DOM-based components. By decoupling the component definitions from the rendering, this becomes possible.

More importantly, this paves the way to writing components that can be shared between the web version of React and React Native. This isn't yet easily possible, but we intend to make this easy in a future version so you can share React code between your website and native apps.

The addons have moved to separate packages as well: react-addons-clone-with-props, react-addons-create-fragment, react-addons-css-transition-group, react-addons-linked-state-mixin, react-addons-pure-render-mixin, react-addons-shallow-compare, react-addons-transition-group, and react-addons-update, plus ReactDOM.unstable_batchedUpdates in react-dom.

For now, please use the same version of react and react-dom in your apps to avoid versioning problems -- but we plan to remove this requirement later. (This release includes the old methods in the react package with a deprecation warning, but they'll be removed completely in 0.15.)

DOM node refs #

The other big change we're making in this release is exposing refs to DOM components as the DOM node itself. That means: we looked at what you can do with a ref to a DOM component and realized that the only useful thing you can do with it is call this.refs.giraffe.getDOMNode() to get the underlying DOM node. In this release, this.refs.giraffe is the actual DOM node.

Refs to custom component classes work exactly as before.

var Zoo = React.createClass({
  render: function() {
    return (
        Giraffe's name: <input ref="giraffe" />

  showName: function() {
    // Previously:
    // var input = this.refs.giraffe.getDOMNode();
    var input = this.refs.giraffe;


This change also applies to the return result of ReactDOM.render when passing a DOM node as the top component. As with refs, this change does not affect custom components (eg. <MyFancyMenu> or <MyContextProvider>), which remain unaffected by this change.

Along with this change, we're also replacing component.getDOMNode() with ReactDOM.findDOMNode(component). The findDOMNode method drills down to find which DOM node was rendered by a component, but it returns its argument when passed a DOM node so it's safe to call on a DOM component too. We introduced this function quietly in the last release, but now we're deprecating .getDOMNode() completely: it should be easy to change all existing calls in your code to be ReactDOM.findDOMNode. We also have an automated codemod script to help you with this transition. Note that the findDOMNode calls are unnecessary when you already have a DOM component ref (as in the example above), so you can (and should) skip them in most cases going forward.

We hope you're as excited about this release as we are! Let us know what you think of it.

Deprecating JSTransform and react-tools

June 12, 2015 by Paul O’Shannessy

Today we're announcing the deprecation of react-tools and JSTransform.

As many people have noticed already, React and React Native have both switched their respective build systems to make use of Babel. This replaced JSTransform, the source transformation tool that we wrote at Facebook. JSTransform has been really good for us over the past several years, however as the JavaScript language continues to evolve, the architecture we used has begun to show its age. We've faced maintenance issues and lagged behind implementing new language features. Last year, Babel (previously 6to5) exploded onto the scene, implementing new features at an amazing pace. Since then it has evolved a solid plugin API, and implemented some of our non-standard language features (JSX and Flow type annotations).

react-tools has always been a very thin wrapper around JSTransform. It has served as a great tool for the community to get up and running, but at this point we're ready to let it go. We won't ship a new version for v0.14.

Migrating to Babel #

Many people in the React and broader JavaScript community have already adopted Babel. It has integrations with a number of tools. Depending on your tool, you'll want to read up on the instructions.

We've been working with the Babel team as we started making use of it and we're confident that it will be the right tool to use with React.

Other Deprecations #

esprima-fb #

As a result of no longer maintaining JSTransform, we no longer have a need to maintain our Esprima fork (esprima-fb). The upstream Esprima and other esprima-based forks, like Espree, have been doing an excellent job of supporting new language features recently. If you have a need of an esprima-based parser, we encourage you to look into using one of those.

Alternatively, if you need to parse JSX, take a look at acorn parser in combination with acorn-jsx plugin which is used inside of Babel and thus always supports the latest syntax.

JSXTransformer #

JSXTransformer is another tool we built specifically for consuming JSX in the browser. It was always intended as a quick way to prototype code before setting up a build process. It would look for <script> tags with type="text/jsx" and then transform and run. This ran the same code that react-tools ran on the server. Babel ships with a nearly identical tool, which has already been integrated into JS Bin.

We'll be deprecating JSXTransformer, however the current version will still be available from various CDNs and Bower.

React Native Release Process

May 22, 2015 by Vjeux

The React Native release process have been a bit chaotic since we open sourced. It was unclear when new code was released, there was no changelog, we bumped the minor and patch version inconsistently and we often had to submit updates right after a release to fix a bad bug. In order to move fast with stable infra, we are introducing a real release process with a two-week release schedule.

To explain how it works, let me walk you through an example. Today, Friday, we took the current state of master and put it on the 0.5-stable branch. We published 0.5.0-rc, an RC (Release Candidate) when we cut the branch. For two weeks, we're going to let it stabilize and only cherry-pick critical bug fixes from master.

Friday in two weeks, we're going to publish the 0.5.0 release, create the 0.6-stable branch and publish 0.6.0-rc as well.

The release process is synchronized with Facebook's mobile release process. This means that everything in the open source release is also being shipped as part of all the Facebook apps that use React Native!

You now have three ways to get React Native. You should chose the one you want based on the amount of risk you tolerate:

  • master: You have updates as soon as they are committed. This is if you want to live on the bleeding edge or want to submit pull requests.
  • rc: If you don't want to update every day and deal with many instabilities but want to have recent updates, this is your best shot.
  • release: This is the most stable version we offer. The trade-off is that it contains commits that are up to a month old.

If you want more details, I highly recommend this video that explains how Facebook mobile release process works and why it was setup this way.

React v0.13.3

May 8, 2015 by Paul O’Shannessy

Today we're sharing another patch release in the v0.13 branch. There are only a few small changes, with a couple to address some issues that arose around that undocumented feature so many of you are already using: context. We also improved developer ergonomics just a little bit, making some warnings better.

The release is now available for download:

We've also published version 0.13.3 of the react and react-tools packages on npm and the react package on bower.

Changelog #

React Core #

New Features #

  • Added clipPath element and attribute for SVG
  • Improved warnings for deprecated methods in plain JS classes

Bug Fixes #

  • Loosened dangerouslySetInnerHTML restrictions so {__html: undefined} will no longer throw
  • Fixed extraneous context warning with non-pure getChildContext
  • Ensure replaceState(obj) retains prototype of obj

React with Add-ons #

Bug Fixes #

  • Test Utils: Ensure that shallow rendering works when components define contextTypes

GraphQL Introduction

May 1, 2015 by Nick Schrock

At the React.js conference in late January 2015, we revealed our next major technology in the React family: Relay.

Relay is a new way of structuring client applications that co-locates data-fetching requirements and React components. Instead of placing data fetching logic in some other part of the client application – or embedding this logic in a custom endpoint on the server – we instead co-locate a declarative data-fetching specification alongside the React component. The language of this declarative specification is GraphQL.

GraphQL was not invented to enable Relay. In fact, GraphQL predates Relay by nearly three years. It was invented during the move from Facebook's HTML5-driven mobile applications to purely native applications. It is a query language for graph data that powers the lion's share of interactions in the Facebook Android and iOS applications. Any user of the native iOS or Android app in the last two years has used an app powered by GraphQL.

We plan to open-source a reference implementation of a GraphQL server and publish a language specification in the coming months. Our goal is to evolve GraphQL to adapt to a wide range of backends, so that projects and companies can use this technology to access their own data. We believe that this is a compelling way to structure servers and to provide powerful abstractions, frameworks and tools – including, but not exclusively, Relay – for product developers.

What is GraphQL? #

A GraphQL query is a string interpreted by a server that returns data in a specified format. Here is an example query:

  user(id: 3500401) {
    profilePicture(size: 50)  {

(Note: this syntax is slightly different from previous GraphQL examples. We've recently been making improvements to the language.)

And here is the response to that query.

  "user" : {
    "id": 3500401,
    "name": "Jing Chen",
    "isViewerFriend": true,
    "profilePicture": {
      "uri": "http://someurl.cdn/pic.jpg",
      "width": 50,
      "height": 50

We will dig into the syntax and semantics of GraphQL in a later post, but even a simple example shows many of its design principles:

  • Hierarchical: Most product development today involves the creation and manipulation of view hierarchies. To achieve congruence with the structure of these applications, a GraphQL query itself is a hierarchical set of fields. The query is shaped just like the data it returns. It is a natural way for product engineers to describe data requirements.
  • Product-centric: GraphQL is unapologetically driven by the requirements of views and the front-end engineers that write them. We start with their way of thinking and requirements and build the language and runtime necessary to enable that.
  • Client-specified queries: In GraphQL, the specification for queries are encoded in the client rather than the server. These queries are specified at field-level granularity. In the vast majority of applications written without GraphQL, the server determines the data returned in its various scripted endpoints. A GraphQL query, on the other hand, returns exactly what a client asks for and no more.
  • Backwards Compatible: In a world of deployed native mobile applications with no forced upgrades, backwards compatibility is a challenge. Facebook, for example, releases apps on a two week fixed cycle and pledges to maintain those apps for at least two years. This means there are at a minimum 52 versions of our clients per platform querying our servers at any given time. Client-specified queries simplifies managing our backwards compatibility guarantees.
  • Structured, Arbitrary Code: Query languages with field-level granularity have typically queried storage engines directly, such as SQL. GraphQL instead imposes a structure onto a server, and exposes fields that are backed by arbitrary code. This allows for both server-side flexibility and a uniform, powerful API across the entire surface area of an application.
  • Application-Layer Protocol: GraphQL is an application-layer protocol and does not require a particular transport. It is a string that is parsed and interpreted by a server.
  • Strongly-typed: GraphQL is strongly-typed. Given a query, tooling can ensure that the query is both syntactically correct and valid within the GraphQL type system before execution, i.e. at development time, and the server can make certain guarantees about the shape and nature of the response. This makes it easier to build high quality client tools.
  • Introspective: GraphQL is introspective. Clients and tools can query the type system using the GraphQL syntax itself. This is a powerful platform for building tools and client software, such as automatic parsing of incoming data into strongly-typed interfaces. It is especially useful in statically typed languages such as Swift, Objective-C and Java, as it obviates the need for repetitive and error-prone code to shuffle raw, untyped JSON into strongly-typed business objects.

Why invent something new? #

Obviously GraphQL is not the first system to manage client-server interactions. In today's world there are two dominant architectural styles for client-server interaction: REST and ad hoc endpoints.


REST, an acronym for Representational State Transfer, is an architectural style rather than a formal protocol. There is actually much debate about what exactly REST is and is not. We wish to avoid such debates. We are interested in the typical attributes of systems that self-identify as REST, rather than systems which are formally REST.

Objects in a typical REST system are addressable by URI and interacted with using verbs in the HTTP protocol. An HTTP GET to a particular URI fetches an object and returns a server-specified set of fields. An HTTP PUT edits an object; an HTTP DELETE deletes an object; and so on.

We believe there are a number of weakness in typical REST systems, ones that are particularly problematic in mobile applications:

  • Fetching complicated object graphs require multiple round trips between the client and server to render single views. For mobile applications operating in variable network conditions, these multiple roundtrips are highly undesirable.
  • Invariably fields and additional data are added to REST endpoints as the system requirements change. However, old clients also receive this additional data as well, because the data fetching specification is encoded on the server rather than the client. As result, these payloads tend to grow over time for all clients. When this becomes a problem for a system, one solution is to overlay a versioning system onto the REST endpoints. Versioning also complicates a server, and results in code duplication, spaghetti code, or a sophisticated, hand-rolled infrastructure to manage it. Another solution to limit over-fetching is to provide multiple views – such as “compact” vs “full” – of the same REST endpoint, however this coarse granularity often does not offer adequate flexibility.
  • REST endpoints are usually weakly-typed and lack machine-readable metadata. While there is much debate about the merits of strong- versus weak-typing in distributed systems, we believe in strong typing because of the correctness guarantees and tooling opportunities it provides. Developers deal with systems that lack this metadata by inspecting frequently out-of-date documentation and then writing code against the documentation.
  • Many of these attributes are linked to the fact that “REST is intended for long-lived network-based applications that span multiple organizations” according to its inventor. This is not a requirement for APIs that serve a client app built within the same organization.

Nearly all externally facing REST APIs we know of trend or end up in these non-ideal states, as well as nearly all internal REST APIs. The consequences of opaqueness and over-fetching are more severe in internal APIs since their velocity of change and level of usage is almost always higher.

Because of multiple round-trips and over-fetching, applications built in the REST style inevitably end up building ad hoc endpoints that are superficially in the REST style. These actually couple the data to a particular view which explicitly violates one of REST's major goals. Most REST systems of any complexity end up as a continuum of endpoints that span from “traditional” REST to ad hoc endpoints.

Ad Hoc Endpoints #

Many applications have no formalized client-server contract. Product developers access server capabilities through ad hoc endpoints and write custom code to fetch the data they need. Servers define procedures, and they return data. This approach has the virtue of simplicity, but can often become untenable as systems age.

  • These systems typically define a custom endpoint per view. For systems with a wide surface area this can quickly grow into a maintenance nightmare of orphaned endpoints, inconsistent tooling, and massive server code duplication. Disciplined engineering organizations can mitigate these issues with great engineering practices, high quality abstractions, and custom tooling. However, given our experience we believe that custom endpoints tend to lead to entropic server codebases.
  • Much like REST, the payloads of custom endpoints grow monotonically (even with mitigation from versioning systems) as the server evolves. Deployed clients cannot break, and, with rapid release cycles and backwards compatibility guarantees, distributed applications will have large numbers of extant versions. Under these constraints it is difficult to remove data from a custom endpoint.
  • Custom endpoints tend to – for a client developer – create a clunky, multi-language, multi-environment development process. No matter if the data has been accessed before in a different view, they are required to first change the custom endpoint, then deploy that code to a server accessible from a mobile device, and only then change the client to utilize that data. In GraphQL – unless the data in the view is completely new to the entire system – a product developer adds a field to a GraphQL query and the work on the client continues unabated.
  • Much like REST, most systems with custom endpoints do not have a formalized type system, which eliminates the possibility for the tools and guarantees that introspective type systems can provide. Some custom-endpoint-driven systems do use a strongly typed serialization scheme, such as Protocol Buffers, Thrift, or XML. Those do allow for direct parsing of responses into typed classes and eliminating boilerplate shuffling from JSON into handwritten classes. These systems are as not as expressive and flexible as GraphQL, and the other downsides of ad hoc endpoints remain.

We believe that GraphQL represents a novel way of structuring the client-server contract. Servers publish a type system specific to their application, and GraphQL provides a unified language to query data within the constraints of that type system. That language allows product developers to express data requirements in a form natural to them: a declarative and hierarchal one.

This is a liberating platform for product developers. With GraphQL, no more contending with ad hoc endpoints or object retrieval with multiple roundtrips to access server data; instead an elegant, hierarchical, declarative query dispatched to a single endpoint. No more frequent jumps between client and server development environments to do experimentation or to change or create views of existing data; instead experiments are done and new views built within a native, client development environment exclusively. No more shuffling unstructured data from ad hoc endpoints into business objects; instead a powerful, introspective type system that serves as a platform for tool building.

Product developers are free to focus on their client software and requirements while rarely leaving their development environment; they can more confidently support shipped clients as a system evolves; and they are using a protocol designed to operate well within the constraints of mobile applications. Product developers can query for exactly what they want, in the way they think about it, across their entire application's data model.

What's next? #

Over the coming months, we will share more technical details about GraphQL, including additional language features, tools that support it, and how it is built and used at Facebook. These posts will culminate in a formal specification of GraphQL to guide implementors across various languages and platforms. We also plan on releasing a reference implementation in the summer, in order to provide a basis for custom deployments and a platform for experimentation. We're incredibly excited to share this system and work with the open source community to improve it.