defer supported only on fragments

[robrichard]

Context

The first experimental implementation of @defer was in Apollo Server and only supported @defer on fields. When applying this to production code, we quickly found that most use-cases were to defer a group of multiple fields, and block the corresponding UI from rendering until all fields in the group have been resolved. This requires the client to track the loading state of each individual field, showing the loading indicator until it receives the asynchronous payloads for each field. Alternatively, a client could render the UI for each individual field as soon as it's ready. However, this could lead to a bad user experience, with the UI repainting and reflowing many times as the data is loaded.

By supporting @defer on fragments, the client is signaling to the server to return the results of the fields in the fragment, when the entire fragment has finished resolving. The client only needs to wait for this payload before rendering the corresponding UI.

Decision

For these reasons, this proposal only supports @defer on fragment spreads and inline fragments. The GraphQL WG is not ruling out supporting @defer on fields in the future if additional use-cases are discovered, but it is no longer being considered for this proposal.

Consequences

If only a single field needs to be deferred, an inline fragment with @defer can easily wrap the field. By not allowing @defer on fields, we hope to discourage bad user experiences caused by many fields loading independently, and provide an easy upgrade path from deferring a single field to deferring many fields.

Status

• defined in spec
• implemented in graphql-js

[nodkz]

I'm sorry but I disagree with your decision.

You considered receiving several fields for rendering one component dependent on that data. And yep gathering them into deferred fragment is a good approach.

But what about deferring fields with Relations roles?

For example, I have an article and comments field which returns a list of comments. And client app with love delays comments rendering. With the @defer directive on the comments field, the graphql query looks more simple and expressive.

According to the current decision the query will be:

query ArticleListPage {
  articles(limit: 10) {
    title
    text
    ... @defer {
       comments {
          text
          createdAt
       }
    }
  }
}

But for me, the most convenient and expressive would be the following query

query ArticleListPage {
  articles(limit: 10) {
    title
    text
    comments @defer  {
      text
      createdAt
    }
  }
}

@robrichard please consider allowing @defer directive for FIELDS. I think clients should be able to decide how to write queries.