Request For Comment: Introducing @defer directive

[vixdug]

Introducing Defer Directive:

We are excited to announce that we are planning to introduce the @defer directive to the Shopify Storefront API. The @defer directive, allows clients to receive data incrementally and defer the execution of certain parts of a query to optimize for quicker initial response times.

How does @defer work?:

The @defer directive is particularly useful when you have parts of a query that are not immediately needed on the initial render of the page or longer running expensive operations. The directive allows you to prioritize the delivery of critical data, and ensure that these essential fields are not blocked by waiting on non-essential data.

When a query fragment is marked with @defer, it signals to the server that this part of the query can be resolved and delivered after the initial response. We will first resolve and deliver the unmarked parts of the query (the non-deferred data). After the initial response, the deferred parts will be resolved. This process will result in a multipart response from a single query. The first response will contain the non-deferred data, and subsequent responses will contain the data from the deferred fields. Each part is delivered to the client as soon as it's ready, allowing the client to progressively update the UI.

How to test:

• Setup Partner store for Developer Preview
• Follow instructions in our tutorial: https://shopify.dev/docs/custom-storefronts/building-with-the-storefront-api/defer

Feedback:

Please submit your feedback by commenting on this post. We'll be accepting feedback until March 18, 2024. After the feedback period, we'll assess all the comments and make a decision on the next steps. We'll keep you updated on any progress or changes.

We're particularly interested in your feedback on:

• Use Cases: How do you plan to use the @defer directive in your applications?
• Compatibility: How does @defer integrate with your existing GQL client?
• Tooling: Any tooling requirements or suggestions for better support?

---

[duncan-fairley]

Wow, this is an incredible addition. We have several Hydrogen storefronts that require very large Storefront queries to fetch (for example) inventory positions on dozens of variants for sibling products that are part of a large product group in a complex catalog.

Our performance optimization efforts thus far have involved edge-caching and breaking larger queries into subqueries that can be executed concurrently and making increasingly heavy use of deferred remix loaders and skeletons for UI dependent on long-running queries.

Would be happy to gather a group of senior engineers from our team to walk through our query structure and how we might use this sort of thing in production.

[vixdug]

@duncan-fairley - Interesting use case! I'd love to chat further with you. We have the developer preview live now if you want to take it for a spin and then we can connect on your experience? 🙌 I'm very interested to see the large queries and response times you are seeing.

[ben-brown-domaine]

Really excited about this. I want to use it on a hybrid build for one of Shopify's biggest stores. Any idea when it will go into prod?

[vixdug]

2024-07 Update 🚀

I'm excited to announce that as of 2024-07, the defer directive is live in the stable release! Alongside this, we've introduced support for Carrier Calculated Shipping rates in the cart. To optimize response times and calculations efficiently, the use of defer is mandatory for fetching deliveryGroups.

Why defer for carrier calculated shipping?
The defer directive in GraphQL allows parts of a query to be executed without having to wait for other parts. This is particularly useful in scenarios like this where carrier rates might take longer to retrieve and process. By deferring deliveryGroups, other fields such as Lines can be prioritized.

Example Query

  cart(id: $cartId) {
  id
    ... DeliveryGroups @defer
  }
}

fragment DeliveryGroups on Cart {
  deliveryGroups(first: 10, withCarrierRates: true) {
    edges {
      node {
        deliveryOptions {
          title
          handle
          estimatedCost {
            amount
            currency
          }
        }
        selectedDeliveryOption {
          title
          handle
          estimatedCost {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

If you encounter any issues or have suggestions - let us know!