Data fetching for React applications #

There's more to building an application than creating a user interface. Data fetching is still a tricky problem, especially as applications become more complicated. At React.js Conf we announced two projects we've created at Facebook to make data fetching simple for developers, even as a product grows to include dozens of contributors and the application becomes as complex as Facebook itself.

The two projects — Relay and GraphQL — have been in use in production at Facebook for some time, and we're excited to be bringing them to the world as open source in the future. In the meantime, we wanted to share some additional information about the projects here.

What is Relay? #

Relay is a new framework from Facebook that provides data-fetching functionality for React applications. It was announced at React.js Conf (January 2015).

Each component specifies its own data dependencies declaratively using a query language called GraphQL. The data is made available to the component via properties on this.props.

Developers compose these React components naturally, and Relay takes care of composing the data queries into efficient batches, providing each component with exactly the data that it requested (and no more), updating those components when the data changes, and maintaining a client-side store (cache) of all data.

What is GraphQL? #

GraphQL is a data querying language designed to describe the complex, nested data dependencies of modern applications. It's been in production use in Facebook's native apps for several years.

On the server, we configure the GraphQL system to map queries to underlying data-fetching code. This configuration layer allows GraphQL to work with arbitrary underlying storage mechanisms. Relay uses GraphQL as its query language, but it is not tied to a specific implementation of GraphQL.

The value proposition #

Relay was born out of our experiences building large applications at Facebook. Our overarching goal is to enable developers to create correct, high-performance applications in a straightforward and obvious way. The design enables even large teams to make changes with a high degree of isolation and confidence. Fetching data is hard, dealing with ever-changing data is hard, and performance is hard. Relay aims to reduce these problems to simple ones, moving the tricky bits into the framework and freeing you to concentrate on building your application.

By co-locating the queries with the view code, the developer can reason about what a component is doing by looking at it in isolation; it's not necessary to consider the context where the component was rendered in order to understand it. Components can be moved anywhere in a render hierarchy without having to apply a cascade of modifications to parent components or to the server code which prepares the data payload.

Co-location leads developers to fall into the "pit of success", because they get exactly the data they asked for and the data they asked for is explicitly defined right next to where it is used. This means that performance becomes the default (it becomes much harder to accidentally over-fetch), and components are more robust (under-fetching is also less likely for the same reason, so components won't try to render missing data and blow up at runtime).

Relay provides a predictable environment for developers by maintaining an invariant: a component won't be rendered until all the data it requested is available. Additionally, queries are defined statically (ie. we can extract queries from a component tree before rendering) and the GraphQL schema provides an authoritative description of what queries are valid, so we can validate queries early and fail fast when the developer makes a mistake.

Only the fields of an object that a component explicitly asks for will be accessible to that component, even if other fields are known and cached in the store (because another component requested them). This makes it impossible for implicit data dependency bugs to exist latently in the system.

By handling all data-fetching via a single abstraction, we're able to handle a bunch of things that would otherwise have to be dealt with repeatedly and pervasively across the application:

• Performance: All queries flow through the framework code, where things that would otherwise be inefficient, repeated query patterns get automatically collapsed and batched into efficient, minimal queries. Likewise, the framework knows which data have been previously requested, or for which requests are currently "in flight", so queries can be automatically de-duplicated and the minimal queries can be produced.
• Subscriptions: All data flows into a single store, and all reads from the store are via the framework. This means the framework knows which components care about which data and which should be re-rendered when data changes; components never have to set up individual subscriptions.
• Common patterns: We can make common patterns easy. Pagination is the example that Jing gave at the conference: if you have 10 records initially, getting the next page just means declaring you want 15 records in total, and the framework automatically constructs the minimal query to grab the delta between what you have and what you need, requests it, and re-renders your view when the data become available.
• Simplified server implementation: Rather than having a proliferation of end-points (per action, per route), a single GraphQL endpoint can serve as a facade for any number of underlying resources.
• Uniform mutations: There is one consistent pattern for performing mutations (writes), and it is conceptually baked into the data querying model itself. You can think of a mutation as a query with side-effects: you provide some parameters that describe the change to be made (eg. attaching a comment to a record) and a query that specifies the data you'll need to update your view of the world after the mutation completes (eg. the comment count on the record), and the data flows through the system using the normal flow. We can do an immediate "optimistic" update on the client (ie. update the view under the assumption that the write will succeed), and finally commit it, retry it or roll it back in the event of an error when the server payload comes back.

How does it relate to Flux? #

In some ways Relay is inspired by Flux, but the mental model is much simpler. Instead of multiple stores, there is one central store that caches all GraphQL data. Instead of explicit subscriptions, the framework itself can track which data each component requests, and which components should be updated whenever the data change. Instead of actions, modifications take the form of mutations.

At Facebook, we have apps built entirely using Flux, entirely using Relay, or with both. One pattern we see emerging is letting Relay manage the bulk of the data flow for an application, but using Flux stores on the side to handle a subset of application state.

Open source plans #

We're working very hard right now on getting both GraphQL (a spec, and a reference implementation) and Relay ready for public release (no specific dates yet, but we are super excited about getting these out there).

In the meantime, we'll be providing more and more information in the form of blog posts (and in other channels). As we get closer to the open source release, you can expect more concrete details, syntax and API descriptions and more.

Watch this space!

It was a privilege to welcome the React community to Facebook HQ on January 28–29 for the first-ever React.js Conf, and a pleasure to be able to unveil three new technologies that we've been using internally at Facebook for some time: GraphQL, Relay, and React Native.

The talks #

Reactions #

The conference is over, but the conversation has just begun.

Mihai Parparita detailed his efforts to hack his way to a React.js Conf ticket; James Long blogged about his first encounter with React Native; Eric Florenzano talked about how he perceives the impact of Relay, GraphQL, and React Native on software development; Margaret Staples blogged about her experience of being on-campus at Facebook HQ; Jeff Barczewski tied his experience of attending the conference up with a bow in this blog post filled with photos, videos, and links; Kevin Old left us with his takeaways; Paul Wittmann found React Native freshly on his radar; and finally, undeterred by not being able to attend the conference in person, Justin Ball summarized it from afar.

And, in case you missed a session, you can borrow Michael Chan’s drawings, Mihai Parparita’s summary, or Shaohua Zhou’s day 1 / day 2 notes.

All proceeds from React.js Conf 2015 were donated to the wonderful programs at code.org. These programs aim to increase access to the field of computer science by underrepresented members of our community. Watch this video to learn more.

React 0.13 has a lot of nice features but there is one particular feature that I'm really excited about. I couldn't wait for React.js Conf to start tomorrow morning.

Maybe you're like me and staying up late excited about the conference, or maybe you weren't one of the lucky ones to get a ticket. Either way I figured I'd give you all something to play with until then.

We just published a beta version of React v0.13.0 to npm! You can install it with npm install react@0.13.0-beta.1. Since this is a pre-release, we don't have proper release notes ready.

So what is that one feature I'm so excited about that I just couldn't wait to share?

Plain JavaScript Classes!! #

JavaScript originally didn't have a built-in class system. Every popular framework built their own, and so did we. This means that you have a learn slightly different semantics for each framework.

We figured that we're not in the business of designing a class system. We just want to use whatever is the idiomatic JavaScript way of creating classes.

In React 0.13.0 you no longer need to use React.createClass to create React components. If you have a transpiler you can use ES6 classes today. You can use the transpiler we ship with react-tools by making use of the harmony option: jsx --harmony.

ES6 Classes #

class HelloMessage extends React.Component {
  render() {
    return <div>Hello {this.props.name}</div>;
  }
}

React.render(<HelloMessage name="Sebastian" />, mountNode);

The API is mostly what you would expect, with the exception of getInitialState. We figured that the idiomatic way to specify class state is to just use a simple instance property. Likewise getDefaultProps and propTypes are really just properties on the constructor.

export class Counter extends React.Component {
  constructor(props) {
    super(props);
    this.state = {count: props.initialCount};
  }
  tick() {
    this.setState({count: this.state.count + 1});
  }
  render() {
    return (
      <div onClick={this.tick.bind(this)}>
        Clicks: {this.state.count}
      </div>
    );
  }
}
Counter.propTypes = { initialCount: React.PropTypes.number };
Counter.defaultProps = { initialCount: 0 };

ES7+ Property Initializers #

Wait, assigning to properties seems like a very imperative way of defining classes! You're right, however, we designed it this way because it's idiomatic. We fully expect a more declarative syntax for property initialization to arrive in future version of JavaScript. It might look something like this:

// Future Version
export class Counter extends React.Component {
  static propTypes = { initialCount: React.PropTypes.number };
  static defaultProps = { initialCount: 0 };
  state = { count: this.props.initialCount };
  tick() {
    this.setState({ count: this.state.count + 1 });
  }
  render() {
    return (
      <div onClick={this.tick.bind(this)}>
        Clicks: {this.state.count}
      </div>
    );
  }
}

This was inspired by TypeScript's property initializers.

Autobinding #

React.createClass has a built-in magic feature that bound all methods to this automatically for you. This can be a little confusing for JavaScript developers that are not used to this feature in other classes, or it can be confusing when they move from React to other classes.

Therefore we decided not to have this built-in into React's class model. You can still explicitly prebind methods in your constructor if you want.

class Counter extends React.Component {
  constructor() {
    super();
    this.tick = this.tick.bind(this);
  }
  tick() {
    ...
  }
  ...
}

However, when we have the future property initializers, there is a neat trick that you can use to accomplish this syntactically:

class Counter extends React.Component {
  tick = () => {
    ...
  }
  ...
}

Mixins #

Unfortunately, we will not launch any mixin support for ES6 classes in React. That would defeat the purpose of only using idiomatic JavaScript concepts.

There is no standard and universal way to define mixins in JavaScript. In fact, several features to support mixins were dropped from ES6 today. There are a lot of libraries with different semantics. We think that there should be one way of defining mixins that you can use for any JavaScript class. React just making another doesn't help that effort.

Therefore, we will keep working with the larger JS community to create a standard for mixins. We will also start designing a new compositional API that will help make common tasks easier to do without mixins. E.g. first-class subscriptions to any kind of Flux store.

Luckily, if you want to keep using mixins, you can just keep using React.createClass.

Note:

The classic React.createClass style of creating classes will continue to work just fine.

Other Languages! #

Since these classes are just plain old JavaScript classes, you can use other languages that compile to JavaScript classes, such as TypeScript.

You can also use CoffeeScript classes:

div = React.createFactory 'div'

class Counter extends React.Component
  @propTypes = initialCount: React.PropTypes.number
  @defaultProps = initialCount: 0

  constructor: (props) ->
    super props
    @state = count: props.initialCount

  tick: =>
    @setState count: @state.count + 1

  render: ->
    div onClick: @tick,
      'Clicks: '
      @state.count

You can even use the old ES3 module pattern if you want:

function MyComponent(initialProps) {
  return {
    state: { value: initialProps.initialValue },
    render: function() {
      return <span className={this.state.value} />
    }
  };
}

Today I'm really happy to announce the React.js Conf Diversity Scholarship! We believe that a diverse set of viewpoints and opinions is really important to build a thriving community. In an ideal world, every part of the tech community would be made up of people from all walks of life. However the reality is that we must be proactive and make an effort to make sure everybody has a voice. As conference organizers we worked closely with the Diversity Team here at Facebook to set aside 10 tickets and provide a scholarship. 10 tickets may not be many in the grand scheme but we really believe that this will have a positive impact on the discussions we have at the conference.

I'm really excited about this and I hope you are too! The full announcement is below:

The Diversity Team at Facebook is excited to announce that we are now accepting applications for the React.js Conf scholarship!

Beginning today, those studying or working in computer science or a related field can apply for an all-expense paid scholarship to attend the React.js Conf at Facebook’s Headquarters in Menlo Park, CA on January 28 & 29, 2015. React opens a world of new possibilities such as server-side rendering, real-time updates, different rendering targets like SVG and canvas. Join us at React.js Conf to shape the future of client-side applications! For more information about the React.js conference, please see the website and previous updates on our blog.

At Facebook, we believe that anyone anywhere can make a positive impact by developing products to make the world more open and connected to the people and things they care about. Given the current realities of the tech industry and the lack of representation of communities we seek to serve, applicants currently under-represented in Computer Science and related fields are strongly encouraged to apply. Facebook will make determinations on scholarship recipients in its sole discretion. Facebook complies with all equal opportunity laws.

To apply for the scholarship, please visit the Application Page: https://www.surveymonkey.com/s/XVJGK6R

Award Includes #

• Paid registration fee for the React.js Conf January 28 & 29th at Facebook’s Headquarters in Menlo Park, CA
• Paid travel and lodging expenses
• Additional $200 meal stipend

Important Dates #

• Monday, January 5, 2015: Applications for the React.js Conf Scholarship must be submitted in full
• Friday, January 9, 2015: Award recipients will be notified by email of their acceptance
• Wednesday & Thursday, January 28 & 29, 2015: React.js Conf

Eligibility #

• Must currently be studying or working in Computer Science or a related field
• International applicants are welcome, but you will be responsible for securing your own visa to attend the conference
• You must be available to attend the full duration of React.js conf on January 28 and 29 at Facebook Headquarters in Menlo Park

We just shipped React v0.12.2, bringing the 0.12 branch up to date with a few small fixes that landed in master over the past 2 months.

You may have noticed that we did not do an announcement for v0.12.1. That release was snuck out in anticipation of Flow, with only transform-related changes. Namely we added a flag to the jsx executable which allowed you to safely transform Flow-based code to vanilla JS. If you didn't update for that release, you can safely skip it and move directly to v0.12.2.

The release is available for download from the CDN:

• React
  Dev build with warnings: https://fb.me/react-0.12.2.js
  Minified build for production: https://fb.me/react-0.12.2.min.js
  
• React with Add-Ons
  Dev build with warnings: https://fb.me/react-with-addons-0.12.2.js
  Minified build for production: https://fb.me/react-with-addons-0.12.2.min.js
  
• In-Browser JSX transformer
  https://fb.me/JSXTransformer-0.12.2.js

We've also published version 0.12.2 of the react and react-tools packages on npm and the react package on bower. 0.12.1 is also available in the same locations if need those.

Please try these builds out and file an issue on GitHub if you see anything awry.

Changelog #

React Core #

• Added support for more HTML attributes: formAction, formEncType, formMethod, formTarget, marginHeight, marginWidth
• Added strokeOpacity to the list of unitless CSS properties
• Removed trailing commas (allows npm module to be bundled and used in IE8)
• Fixed bug resulting in error when passing undefined to React.createElement - now there is a useful warning

React Tools #

• JSX-related transforms now always use double quotes for props and displayName