From d23d286876c000cb57af75944c71bea969776f16 Mon Sep 17 00:00:00 2001 From: Rose Koron Date: Thu, 12 May 2022 18:06:55 -0700 Subject: [PATCH 1/4] Half way through cache --- docs/source/why-apollo.mdx | 109 +++++++++++++++++++++++-------------- 1 file changed, 68 insertions(+), 41 deletions(-) diff --git a/docs/source/why-apollo.mdx b/docs/source/why-apollo.mdx index 2358adc7651..cb4815a3dab 100644 --- a/docs/source/why-apollo.mdx +++ b/docs/source/why-apollo.mdx @@ -3,14 +3,20 @@ title: Why Apollo Client? description: Why choose Apollo Client to manage your data? --- -Data management shouldn't have to be so difficult! If you're wondering how to simplify managing remote and local data in your React application, then you've come to the right place. Throughout this documentation, you'll learn how Apollo's intelligent caching and declarative approach to data fetching can help you iterate faster while writing less code. Let's jump right in! 🚀 +Apollo Client is a state management library that simplifies managing remote and local data with GraphQL. Apollo Client's intelligent caching and declarative approach to data fetching can help you iterate faster while writing less code. Additionally, if you need custom functionality, you can create your dream client by building extensions on top of Apollo Client. + +Let's jump right into what Apollo Client can offer you! 🚀 ## Declarative data fetching -With Apollo's declarative approach to data fetching, all of the logic for retrieving your data, tracking loading and error states, and updating your UI is encapsulated by the `useQuery` Hook. This encapsulation makes integrating query results into your presentational components a breeze! Let's see what this looks like in practice with Apollo Client and React: +Apollo Client handles the request cycle from start to finish, including tracking loading and error states. There's no middleware or boilerplate code to set up before making your first request, and you don't need to worry about transforming or caching responses. All you have to do is describe the data your component needs and let Apollo Client do the heavy lifting. 💪 + +Apollo Client's `useQuery` hook leverages React's [Hooks API](https://reactjs.org/docs/hooks-intro.html) to bind a query to a component, enabling that component to render a query's results immediately. The `useQuery` hook encapsulates the logic for retrieving your data, tracking loading and error states, and updating your UI. This encapsulation makes integrating query results into your presentational components a breeze! + +Let's see what this looks like in practice with Apollo Client and React: ```jsx -function Feed() { +function ShowDogs() { const { loading, error, data } = useQuery(GET_DOGS); if (error) return ; if (loading) return ; @@ -19,25 +25,59 @@ function Feed() { } ``` -Here we're using the `useQuery` Hook to fetch some dogs from our GraphQL server and display them in a list. `useQuery` leverages React's [Hooks API](https://reactjs.org/docs/hooks-intro.html) to bind a query to our component and render it based on the results of our query. Once our data comes back, our `` component will update reactively with the data it needs. +In the example above, we're using the `useQuery` hook to fetch dogs from our GraphQL server and display them in a list. Once our data comes back, our `` component will reactively update to display the new data. + +When switching to Apollo Client, you'll find you can remove much of your previous code related to data management. Some teams have reported deleting thousands of lines of code! + +Though you'll find yourself writing less code with Apollo Client, that doesn't mean you have to compromise on features. [The `useQuery` hook](./data/queries#usequery-api) supports advanced features like an optimistic UI, refetching, and pagination. + +## Combining local & remote data + +Thousands of developers have told us that Apollo Client excels at managing remote data, equating to roughly 80% of their data needs. But what about local data (e.g., global flags or device API results), which makes up the other 20% of the pie? + +Apollo Client includes [local state management](local-state/local-state-management/) features straight out of the box, enabling you to use your Apollo cache as the single source of truth for your application's data. + +By using Apollo Client's local state functionality, you can include local fields _and_ remotely fetched fields in the same query: + +```js +const GET_DOG = gql` + query GetDogByBreed($breed: String!) { + dog(breed: $breed) { + images { + url + id + isLiked @client + } + } + } +`; +``` -Apollo Client takes care of the request cycle from start to finish, including tracking loading and error states for you. There's no middleware to set up or boilerplate to write before making your first request, nor do you need to worry about transforming and caching the response. All you have to do is describe the data your component needs and let Apollo Client do the heavy lifting. 💪 +In the above example, we're querying the [local-only field](./local-state/managing-state-with-field-policies) `isLiked` and fetching data from our GraphQL server. Your components contain local and remote data; now, your queries can too! -You'll find that when you switch to Apollo Client, you'll be able to delete a lot of unnecessary code related to data management. The exact amount will vary depending on your application, but some teams have reported up to thousands of lines. While you'll find yourself writing less code with Apollo, that doesn't mean you have to compromise on features! Advanced features like optimistic UI, refetching, and pagination are all easily accessible through `useQuery` options. +Managing your data with Apollo Client lets you take advantage of GraphQL as a unified interface for _all_ of your data. Using the [Apollo Client Devtools](./development-testing/developer-tooling#apollo-client-devtools), you can inspect both your local and remote schemas using GraphiQL. ## Zero-config caching -One of the key features that sets Apollo Client apart from other data management solutions is its normalized cache. Apollo Client includes an intelligent cache out of the box, that requires very little configuration to get started with. +Caching a graph is no easy task, but we've spent years solving this problem. Normalization is the key to maintaining consistent data across multiple components in an application. + +One of the key features that sets Apollo Client apart from other data management solutions is its local, in-memory, [normalized](./caching/overview#data-normalization) cache. + +The Apollo Client cache is easy to get started with, and [configure](./caching/cache-configuration) as you need: ```js -import { ApolloClient, InMemoryCache } from '@apollo/client'; +import { ApolloClient, InMemoryCache } from "@apollo/client"; const client = new ApolloClient({ - cache: new InMemoryCache() + cache: new InMemoryCache(), }); ``` -Caching a graph is no easy task, but we've spent two years focused on solving it. Since you can have multiple paths leading to the same data, normalization is essential for keeping your data consistent across multiple components. Let's look at some practical examples: +Once your in-memory cache has been created, whenever Apollo Client receives query response data it will automatically identify the distinct objects (those with a `__typename` and an `id` property) into their own entities and store them within the cache. This guarantees that returning a value from a mutation with an id will automatically update any queries that fetch the object with the same id. It also ensures that two queries which return the same data will always be in sync. + +Let's look at some practical examples at how the cache can help make your application efficient! + +The below query, `GET_ALL_DOGS`, fetches a list of dogs and their `displayImage`s: ```js const GET_ALL_DOGS = gql` @@ -49,7 +89,11 @@ const GET_ALL_DOGS = gql` } } `; +``` +The below mutation, `UPDATE_DISPLAY_IMAGE`, updates a single dog's `displayImage`: + +```js const UPDATE_DISPLAY_IMAGE = gql` mutation UpdateDisplayImage($id: String!, $displayImage: String!) { updateDisplayImage(id: $id, displayImage: $displayImage) { @@ -60,9 +104,9 @@ const UPDATE_DISPLAY_IMAGE = gql` `; ``` -The query, `GET_ALL_DOGS`, fetches a list of dogs and their `displayImage`. The mutation, `UPDATE_DISPLAY_IMAGE`, updates a single dog's `displayImage`. If we update the `displayImage` on a specific dog, we also need that item on the list of all dogs to reflect the new data. Apollo Client splits out each object in a GraphQL result with a `__typename` and an `id` property into its own entry in the Apollo cache. This guarantees that returning a value from a mutation with an id will automatically update any queries that fetch the object with the same id. It also ensures that two queries which return the same data will always be in sync. +If we run the `UPDATE_DISPLAY_IMAGE` mutation, we want to ensure that our newly updated dog's image is updated everywhere in our application. -Features that are normally complicated to execute are trivial to build with the Apollo cache. Let's go back to our `GET_ALL_DOGS` query from the previous example that displays a list of dogs. What if we want to transition to a detail page for a specific dog? Since we've already fetched information on each dog, we don't want to refetch the same information from our server. Thanks to Apollo Client's cache policies API, we can connect the *dogs* between two queries so we don't have to fetch information that we know is already available. +Let's go back to our `GET_ALL_DOGS` query from the previous example that displays a list of dogs. What if we want to transition to a detail page for a specific dog? Since we've already fetched information on each dog, we don't want to refetch the same information from our server. Thanks to Apollo Client's cache policies API, we can connect the _dogs_ between two queries so we don't have to fetch information that we know is already available. Here's what our query for one dog looks like: @@ -78,10 +122,10 @@ const GET_DOG = gql` `; ``` -Here we define a custom `FieldPolicy` that returns a reference to the cached `Dog` data, which our query can then use to retrieve that data. +Below we define a custom [`FieldPolicy`](./caching/advanced-topics/#cache-redirects) that returns a reference to the cached `Dog` data, which our query can then use to retrieve that data. ```js -import { ApolloClient, InMemoryCache } from '@apollo/client'; +import { ApolloClient, InMemoryCache } from "@apollo/client"; const cache = new InMemoryCache({ typePolicies: { @@ -89,48 +133,31 @@ const cache = new InMemoryCache({ fields: { dog(_, { args, toReference }) { return toReference({ - __typename: 'Dog', + __typename: "Dog", id: args.id, }); - } - } - } - } + }, + }, + }, + }, }); const client = new ApolloClient({ cache }); ``` -## Combine local & remote data - -Thousands of developers have told us that Apollo Client excels at managing remote data, which equates to roughly 80% of their data needs. But what about local data (like global flags and device API results) that make up the other 20% of the pie? Apollo Client includes [local state management](local-state/local-state-management/) features out of the box, that allow you to use your Apollo cache as the single source of truth for data in your application. - -Managing all your data with Apollo Client allows you to take advantage of GraphQL as a unified interface to all of your data. This enables you to inspect both your local and remote schemas in the Apollo Client Devtools through GraphiQL. - -```js -const GET_DOG = gql` - query GetDogByBreed($breed: String!) { - dog(breed: $breed) { - images { - url - id - isLiked @client - } - } - } -`; -``` - -By leveraging Apollo Client's local state functionality, you can add client-side only fields to your remote data seamlessly and query them from your components. In this example, we're querying the client-only field `isLiked` alongside our server data. Your components are made up of local and remote data, now your queries can be too! +> Learn more about [Caching in Apollo Client](https://www.apollographql.com/docs/react/caching/overview). ## Vibrant ecosystem Apollo Client is easy to get started with, but extensible for when you need to build out more advanced features. If you need custom functionality that isn't covered with `@apollo/client`, such as app-specific middleware or cache persistence, you can leverage the Apollo Link architecture to plug-in new network stack functionality. This flexibility makes it simple to create your dream client by building extensions on top of Apollo. We're always really impressed by what our contributors have built on top of Apollo - check out some of their packages: + - [`apollo3-cache-persist`](https://github.com/apollographql/apollo-cache-persist): Simple persistence for your Apollo cache ([@jamesreggio](https://github.com/jamesreggio)) - [`apollo-storybook-decorator`](https://github.com/abhiaiyer91/apollo-storybook-decorator): Wrap your React Storybook stories with Apollo Client ([@abhiaiyer91](https://github.com/abhiaiyer91)) - [AppSync by AWS](https://blog.apollographql.com/aws-appsync-powered-by-apollo-df61eb706183): Amazon's real-time GraphQL client uses Apollo Client under the hood +- [`apollo-augmented-hooks`](https://github.com/appmotion/apollo-augmented-hooks): Adding additional functionality for Apollo Client's hooks ([appmotion](https://github.com/appmotion)) +- [`apollo-cache-policies`](https://github.com/NerdWalletOSS/apollo-cache-policies): Extending Apollo Client's cache with support for advanced cache policies ([NerdWalletOSS](https://github.com/NerdWalletOSS)) When you choose Apollo to manage your data, you also gain the support of our amazing community. There are thousands of developers in our [community forums](https://community.apollographql.com) for you to share ideas with. You can also read articles on best practices and our announcements on the [Apollo blog](https://blog.apollographql.com/), updated frequently. @@ -141,7 +168,7 @@ Companies ranging from enterprises to startups trust Apollo Client to power thei - [The New York Times](https://open.nytimes.com/the-new-york-times-now-on-apollo-b9a78a5038c): Learn how The New York Times switched from Relay to Apollo & implemented features in their app such as SSR and persisted queries - [Express](https://blog.apollographql.com/changing-the-architecture-of-express-com-23c950d43323): Easy-to-use pagination with Apollo helped improve the Express eCommerce team's key product pages - [Major League Soccer](https://blog.apollographql.com/reducing-our-redux-code-with-react-apollo-5091b9de9c2a): MLS' switch from Redux to Apollo for state management enabled them to delete nearly all of their Redux code -- [Expo](https://blog.apollographql.com/using-graphql-apollo-at-expo-4c1f21f0f115): Developing their React Native app with Apollo allowed the Expo engineers to focus on improving their product instead of writing data fetching logic +- [Expo](https://blog.apollographql.com/using-graphql-apollo-at-expo-4c1f21f0f115): Developing their React Native app with Apollo enabled the Expo engineers to focus on improving their product instead of writing data fetching logic - [KLM](https://youtu.be/T2njjXHdKqw): Learn how the KLM team scaled their Angular app with GraphQL and Apollo If your company is using Apollo Client in production, we'd love to feature a case study on our blog! Please get in touch via [our community forums](https://community.apollographql.com) so we can learn more about how you're using Apollo. Alternatively, if you already have a blog post or a conference talk that you'd like to feature here, please send in a PR. From feb4f2beb51ec0f1fac84ddc8fb37667fbb3d50e Mon Sep 17 00:00:00 2001 From: Rose Koron Date: Fri, 13 May 2022 13:14:49 -0700 Subject: [PATCH 2/4] First draft done --- docs/source/why-apollo.mdx | 44 +++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/docs/source/why-apollo.mdx b/docs/source/why-apollo.mdx index cb4815a3dab..d15e15093cf 100644 --- a/docs/source/why-apollo.mdx +++ b/docs/source/why-apollo.mdx @@ -13,7 +13,7 @@ Apollo Client handles the request cycle from start to finish, including tracking Apollo Client's `useQuery` hook leverages React's [Hooks API](https://reactjs.org/docs/hooks-intro.html) to bind a query to a component, enabling that component to render a query's results immediately. The `useQuery` hook encapsulates the logic for retrieving your data, tracking loading and error states, and updating your UI. This encapsulation makes integrating query results into your presentational components a breeze! -Let's see what this looks like in practice with Apollo Client and React: +Let's see what this looks like in practice with Apollo Client for React: ```jsx function ShowDogs() { @@ -53,17 +53,17 @@ const GET_DOG = gql` `; ``` -In the above example, we're querying the [local-only field](./local-state/managing-state-with-field-policies) `isLiked` and fetching data from our GraphQL server. Your components contain local and remote data; now, your queries can too! +In the above example, we're querying the [local-only field](./local-state/managing-state-with-field-policies) `isLiked` while fetching data from our GraphQL server. Your components contain local and remote data; now, your queries can too! Managing your data with Apollo Client lets you take advantage of GraphQL as a unified interface for _all_ of your data. Using the [Apollo Client Devtools](./development-testing/developer-tooling#apollo-client-devtools), you can inspect both your local and remote schemas using GraphiQL. ## Zero-config caching -Caching a graph is no easy task, but we've spent years solving this problem. Normalization is the key to maintaining consistent data across multiple components in an application. +Caching a graph is no easy task, but we've spent years solving this problem. We've found that _normalization_ is the key to maintaining consistent data across multiple components in an application. One of the key features that sets Apollo Client apart from other data management solutions is its local, in-memory, [normalized](./caching/overview#data-normalization) cache. -The Apollo Client cache is easy to get started with, and [configure](./caching/cache-configuration) as you need: +The Apollo Client cache is easy to get started with and [configure](./caching/cache-configuration) as you go: ```js import { ApolloClient, InMemoryCache } from "@apollo/client"; @@ -73,11 +73,11 @@ const client = new ApolloClient({ }); ``` -Once your in-memory cache has been created, whenever Apollo Client receives query response data it will automatically identify the distinct objects (those with a `__typename` and an `id` property) into their own entities and store them within the cache. This guarantees that returning a value from a mutation with an id will automatically update any queries that fetch the object with the same id. It also ensures that two queries which return the same data will always be in sync. +Once you've passed your cache to `ApolloClient`, whenever Apollo Client receives query response data, it will automatically attempt to identify and store the distinct objects (i.e., those with a `__typename` and an id property) from a query's data into separate entries within its cache. -Let's look at some practical examples at how the cache can help make your application efficient! +Let's look at some practical examples of how this caching mechanism can make your application more efficient. -The below query, `GET_ALL_DOGS`, fetches a list of dogs and their `displayImage`s: +The below query, `GET_ALL_DOGS`, fetches a list of dogs and information about each dog: ```js const GET_ALL_DOGS = gql` @@ -91,7 +91,7 @@ const GET_ALL_DOGS = gql` `; ``` -The below mutation, `UPDATE_DISPLAY_IMAGE`, updates a single dog's `displayImage`: +The below mutation, `UPDATE_DISPLAY_IMAGE`, updates a specified dog's `displayImage` and returns the updated dog: ```js const UPDATE_DISPLAY_IMAGE = gql` @@ -104,11 +104,15 @@ const UPDATE_DISPLAY_IMAGE = gql` `; ``` -If we run the `UPDATE_DISPLAY_IMAGE` mutation, we want to ensure that our newly updated dog's image is updated everywhere in our application. +When we run the `UPDATE_DISPLAY_IMAGE` mutation, we want to ensure that our dog's image is updated _everywhere_ in our application. We also need to ensure we update any previously cached data about that dog. -Let's go back to our `GET_ALL_DOGS` query from the previous example that displays a list of dogs. What if we want to transition to a detail page for a specific dog? Since we've already fetched information on each dog, we don't want to refetch the same information from our server. Thanks to Apollo Client's cache policies API, we can connect the _dogs_ between two queries so we don't have to fetch information that we know is already available. +Our `UPDATE_DISPLAY_IMAGE` mutation returns the object the mutation modified (i.e., the `id` and `displayImage` of the dog), enabling Apollo Client to automatically overwrite the existing fields of any _previously cached_ object with the same `id`. Tying it all together, if we've already run the `GET_ALL_DOGS` query before Apollo Client runs the `UPDATE_DISPLAY_IMAGE` mutation, it will _automatically_ update the changed dog's `displayImage` in our local cache. ✨ -Here's what our query for one dog looks like: +> For more examples of updating a cache with mutations, see [Updating the cache directly](./data/mutations#updating-the-cache-directly). + +The ability to update our cache under the hood can also help in scenarios where we want to avoid _refetching_ information already contained in our cache. + +For example, let's say we want to navigate to the details page for a particular dog. Here's what the query would look like: ```js const GET_DOG = gql` @@ -122,7 +126,9 @@ const GET_DOG = gql` `; ``` -Below we define a custom [`FieldPolicy`](./caching/advanced-topics/#cache-redirects) that returns a reference to the cached `Dog` data, which our query can then use to retrieve that data. +If we've run the above `GET_ALL_DOGS` query at any point, the data for our `GET_DOG` query might _already_ be in our local cache. We can tell Apollo Client where to check first for any cached `Dog` objects, avoiding refetching information if it already exists in our cache. + +Below we define a custom [`FieldPolicy`](./caching/advanced-topics/#cache-redirects) that returns a reference to our previously cached `Dog` object data: ```js import { ApolloClient, InMemoryCache } from "@apollo/client"; @@ -145,13 +151,15 @@ const cache = new InMemoryCache({ const client = new ApolloClient({ cache }); ``` +The above field policy enables our `GET_DOG` query to read previously stored data straight from our cache instead of sending off an unnecessary query. + > Learn more about [Caching in Apollo Client](https://www.apollographql.com/docs/react/caching/overview). ## Vibrant ecosystem -Apollo Client is easy to get started with, but extensible for when you need to build out more advanced features. If you need custom functionality that isn't covered with `@apollo/client`, such as app-specific middleware or cache persistence, you can leverage the Apollo Link architecture to plug-in new network stack functionality. +Apollo Client is easy to get started with but extensible enough for when you want to build out more advanced features. If you need custom functionality that `@apollo/client` doesn't cover, you can use [Apollo Link's architecture](./api/link/introduction) to create your dream client by building an extension on top of Apollo Client. -This flexibility makes it simple to create your dream client by building extensions on top of Apollo. We're always really impressed by what our contributors have built on top of Apollo - check out some of their packages: +We're always impressed by what our contributors have built on top of Apollo Client. Check out some of our community's extensions below: - [`apollo3-cache-persist`](https://github.com/apollographql/apollo-cache-persist): Simple persistence for your Apollo cache ([@jamesreggio](https://github.com/jamesreggio)) - [`apollo-storybook-decorator`](https://github.com/abhiaiyer91/apollo-storybook-decorator): Wrap your React Storybook stories with Apollo Client ([@abhiaiyer91](https://github.com/abhiaiyer91)) @@ -159,11 +167,13 @@ This flexibility makes it simple to create your dream client by building extensi - [`apollo-augmented-hooks`](https://github.com/appmotion/apollo-augmented-hooks): Adding additional functionality for Apollo Client's hooks ([appmotion](https://github.com/appmotion)) - [`apollo-cache-policies`](https://github.com/NerdWalletOSS/apollo-cache-policies): Extending Apollo Client's cache with support for advanced cache policies ([NerdWalletOSS](https://github.com/NerdWalletOSS)) -When you choose Apollo to manage your data, you also gain the support of our amazing community. There are thousands of developers in our [community forums](https://community.apollographql.com) for you to share ideas with. You can also read articles on best practices and our announcements on the [Apollo blog](https://blog.apollographql.com/), updated frequently. +When you choose to use Apollo Client to manage your data, you also gain the support of our fantastic community. There are thousands of developers in our [community forums](https://community.apollographql.com) for you to share ideas with. + +You can also read articles on best practices and announcements on the frequently updated [Apollo blog](https://blog.apollographql.com/). ## Case studies -Companies ranging from enterprises to startups trust Apollo Client to power their most critical web & native applications. If you'd like to learn more about how transitioning to GraphQL and Apollo simplified their engineers' workflows and improved their products, check out these case studies: +Companies ranging from enterprises to startups trust Apollo Client to power their most critical web and native applications. If you'd like to learn more about how transitioning to GraphQL and Apollo simplified engineers' workflows and improved companies' products, check out these case studies: - [The New York Times](https://open.nytimes.com/the-new-york-times-now-on-apollo-b9a78a5038c): Learn how The New York Times switched from Relay to Apollo & implemented features in their app such as SSR and persisted queries - [Express](https://blog.apollographql.com/changing-the-architecture-of-express-com-23c950d43323): Easy-to-use pagination with Apollo helped improve the Express eCommerce team's key product pages @@ -171,4 +181,4 @@ Companies ranging from enterprises to startups trust Apollo Client to power thei - [Expo](https://blog.apollographql.com/using-graphql-apollo-at-expo-4c1f21f0f115): Developing their React Native app with Apollo enabled the Expo engineers to focus on improving their product instead of writing data fetching logic - [KLM](https://youtu.be/T2njjXHdKqw): Learn how the KLM team scaled their Angular app with GraphQL and Apollo -If your company is using Apollo Client in production, we'd love to feature a case study on our blog! Please get in touch via [our community forums](https://community.apollographql.com) so we can learn more about how you're using Apollo. Alternatively, if you already have a blog post or a conference talk that you'd like to feature here, please send in a PR. +If your company uses Apollo Client in production, we'd love to feature a case study on our blog! Please get in touch via [our community forums](https://community.apollographql.com) so we can learn more about how you're using Apollo. Alternatively, please send in a PR if you already have a blog post or a conference talk that you'd like to feature here. From 503ec9dceae6cb68601f36195738c5f7f6d3dd5f Mon Sep 17 00:00:00 2001 From: Rose Koron Date: Fri, 13 May 2022 13:17:41 -0700 Subject: [PATCH 3/4] Small tweaks --- docs/source/why-apollo.mdx | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/source/why-apollo.mdx b/docs/source/why-apollo.mdx index d15e15093cf..3085f79ff9b 100644 --- a/docs/source/why-apollo.mdx +++ b/docs/source/why-apollo.mdx @@ -25,7 +25,7 @@ function ShowDogs() { } ``` -In the example above, we're using the `useQuery` hook to fetch dogs from our GraphQL server and display them in a list. Once our data comes back, our `` component will reactively update to display the new data. +In the example above, we're using the `useQuery` hook to fetch dogs from our GraphQL server and display them in a list. Once our data comes back, our `` component reactively updates to display the new data. When switching to Apollo Client, you'll find you can remove much of your previous code related to data management. Some teams have reported deleting thousands of lines of code! @@ -73,7 +73,7 @@ const client = new ApolloClient({ }); ``` -Once you've passed your cache to `ApolloClient`, whenever Apollo Client receives query response data, it will automatically attempt to identify and store the distinct objects (i.e., those with a `__typename` and an id property) from a query's data into separate entries within its cache. +Once you've passed your cache to `ApolloClient`, whenever Apollo Client receives query response data, it automatically attempts to identify and store the distinct objects (i.e., those with a `__typename` and an id property) from a query's data into separate entries within its cache. Let's look at some practical examples of how this caching mechanism can make your application more efficient. @@ -106,7 +106,7 @@ const UPDATE_DISPLAY_IMAGE = gql` When we run the `UPDATE_DISPLAY_IMAGE` mutation, we want to ensure that our dog's image is updated _everywhere_ in our application. We also need to ensure we update any previously cached data about that dog. -Our `UPDATE_DISPLAY_IMAGE` mutation returns the object the mutation modified (i.e., the `id` and `displayImage` of the dog), enabling Apollo Client to automatically overwrite the existing fields of any _previously cached_ object with the same `id`. Tying it all together, if we've already run the `GET_ALL_DOGS` query before Apollo Client runs the `UPDATE_DISPLAY_IMAGE` mutation, it will _automatically_ update the changed dog's `displayImage` in our local cache. ✨ +Our `UPDATE_DISPLAY_IMAGE` mutation returns the object the mutation modified (i.e., the `id` and `displayImage` of the dog), enabling Apollo Client to automatically overwrite the existing fields of any _previously cached_ object with the same `id`. Tying it all together, if we've already run the `GET_ALL_DOGS` query before Apollo Client runs the `UPDATE_DISPLAY_IMAGE` mutation, it _automatically_ updates the changed dog's `displayImage` in our local cache. ✨ > For more examples of updating a cache with mutations, see [Updating the cache directly](./data/mutations#updating-the-cache-directly). @@ -161,11 +161,11 @@ Apollo Client is easy to get started with but extensible enough for when you wan We're always impressed by what our contributors have built on top of Apollo Client. Check out some of our community's extensions below: -- [`apollo3-cache-persist`](https://github.com/apollographql/apollo-cache-persist): Simple persistence for your Apollo cache ([@jamesreggio](https://github.com/jamesreggio)) -- [`apollo-storybook-decorator`](https://github.com/abhiaiyer91/apollo-storybook-decorator): Wrap your React Storybook stories with Apollo Client ([@abhiaiyer91](https://github.com/abhiaiyer91)) -- [AppSync by AWS](https://blog.apollographql.com/aws-appsync-powered-by-apollo-df61eb706183): Amazon's real-time GraphQL client uses Apollo Client under the hood -- [`apollo-augmented-hooks`](https://github.com/appmotion/apollo-augmented-hooks): Adding additional functionality for Apollo Client's hooks ([appmotion](https://github.com/appmotion)) -- [`apollo-cache-policies`](https://github.com/NerdWalletOSS/apollo-cache-policies): Extending Apollo Client's cache with support for advanced cache policies ([NerdWalletOSS](https://github.com/NerdWalletOSS)) +- [`apollo3-cache-persist`](https://github.com/apollographql/apollo-cache-persist): Simple persistence for your Apollo cache ([@jamesreggio](https://github.com/jamesreggio)). +- [`apollo-storybook-decorator`](https://github.com/abhiaiyer91/apollo-storybook-decorator): Wrap your React Storybook stories with Apollo Client ([@abhiaiyer91](https://github.com/abhiaiyer91)). +- [AppSync by AWS](https://blog.apollographql.com/aws-appsync-powered-by-apollo-df61eb706183): Amazon's real-time GraphQL client uses Apollo Client under the hood. +- [`apollo-augmented-hooks`](https://github.com/appmotion/apollo-augmented-hooks): Adding additional functionality for Apollo Client's hooks ([appmotion](https://github.com/appmotion)). +- [`apollo-cache-policies`](https://github.com/NerdWalletOSS/apollo-cache-policies): Extending Apollo Client's cache with support for advanced cache policies ([NerdWalletOSS](https://github.com/NerdWalletOSS)). When you choose to use Apollo Client to manage your data, you also gain the support of our fantastic community. There are thousands of developers in our [community forums](https://community.apollographql.com) for you to share ideas with. @@ -175,10 +175,10 @@ You can also read articles on best practices and announcements on the frequently Companies ranging from enterprises to startups trust Apollo Client to power their most critical web and native applications. If you'd like to learn more about how transitioning to GraphQL and Apollo simplified engineers' workflows and improved companies' products, check out these case studies: -- [The New York Times](https://open.nytimes.com/the-new-york-times-now-on-apollo-b9a78a5038c): Learn how The New York Times switched from Relay to Apollo & implemented features in their app such as SSR and persisted queries -- [Express](https://blog.apollographql.com/changing-the-architecture-of-express-com-23c950d43323): Easy-to-use pagination with Apollo helped improve the Express eCommerce team's key product pages -- [Major League Soccer](https://blog.apollographql.com/reducing-our-redux-code-with-react-apollo-5091b9de9c2a): MLS' switch from Redux to Apollo for state management enabled them to delete nearly all of their Redux code -- [Expo](https://blog.apollographql.com/using-graphql-apollo-at-expo-4c1f21f0f115): Developing their React Native app with Apollo enabled the Expo engineers to focus on improving their product instead of writing data fetching logic -- [KLM](https://youtu.be/T2njjXHdKqw): Learn how the KLM team scaled their Angular app with GraphQL and Apollo +- [The New York Times](https://open.nytimes.com/the-new-york-times-now-on-apollo-b9a78a5038c): Learn how The New York Times switched from Relay to Apollo & implemented features in their app such as SSR and persisted queries. +- [Express](https://blog.apollographql.com/changing-the-architecture-of-express-com-23c950d43323): Easy-to-use pagination with Apollo helped improve the Express eCommerce team's key product pages. +- [Major League Soccer](https://blog.apollographql.com/reducing-our-redux-code-with-react-apollo-5091b9de9c2a): MLS' switch from Redux to Apollo for state management enabled them to delete nearly all of their Redux code. +- [Expo](https://blog.apollographql.com/using-graphql-apollo-at-expo-4c1f21f0f115): Developing their React Native app with Apollo enabled the Expo engineers to focus on improving their product instead of writing data fetching logic. +- [KLM](https://youtu.be/T2njjXHdKqw): Learn how the KLM team scaled their Angular app with GraphQL and Apollo. If your company uses Apollo Client in production, we'd love to feature a case study on our blog! Please get in touch via [our community forums](https://community.apollographql.com) so we can learn more about how you're using Apollo. Alternatively, please send in a PR if you already have a blog post or a conference talk that you'd like to feature here. From 529f18013c6f289740d6a3fc1d2465f959e8c6f7 Mon Sep 17 00:00:00 2001 From: Rose M Koron <32436232+rkoron007@users.noreply.github.com> Date: Fri, 13 May 2022 14:21:35 -0700 Subject: [PATCH 4/4] Apply suggestions from JV code review Co-authored-by: JV --- docs/source/why-apollo.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/why-apollo.mdx b/docs/source/why-apollo.mdx index 3085f79ff9b..8528182d858 100644 --- a/docs/source/why-apollo.mdx +++ b/docs/source/why-apollo.mdx @@ -66,7 +66,7 @@ One of the key features that sets Apollo Client apart from other data management The Apollo Client cache is easy to get started with and [configure](./caching/cache-configuration) as you go: ```js -import { ApolloClient, InMemoryCache } from "@apollo/client"; +import { ApolloClient, InMemoryCache } from '@apollo/client'; const client = new ApolloClient({ cache: new InMemoryCache(), @@ -131,7 +131,7 @@ If we've run the above `GET_ALL_DOGS` query at any point, the data for our `GET_ Below we define a custom [`FieldPolicy`](./caching/advanced-topics/#cache-redirects) that returns a reference to our previously cached `Dog` object data: ```js -import { ApolloClient, InMemoryCache } from "@apollo/client"; +import { ApolloClient, InMemoryCache } from '@apollo/client'; const cache = new InMemoryCache({ typePolicies: { @@ -139,7 +139,7 @@ const cache = new InMemoryCache({ fields: { dog(_, { args, toReference }) { return toReference({ - __typename: "Dog", + __typename: 'Dog', id: args.id, }); }, @@ -181,4 +181,4 @@ Companies ranging from enterprises to startups trust Apollo Client to power thei - [Expo](https://blog.apollographql.com/using-graphql-apollo-at-expo-4c1f21f0f115): Developing their React Native app with Apollo enabled the Expo engineers to focus on improving their product instead of writing data fetching logic. - [KLM](https://youtu.be/T2njjXHdKqw): Learn how the KLM team scaled their Angular app with GraphQL and Apollo. -If your company uses Apollo Client in production, we'd love to feature a case study on our blog! Please get in touch via [our community forums](https://community.apollographql.com) so we can learn more about how you're using Apollo. Alternatively, please send in a PR if you already have a blog post or a conference talk that you'd like to feature here. +If your company uses Apollo Client in production, we'd love to feature a case study on our blog! Please get in touch via [our community forums](https://community.apollographql.com) so we can learn more about how you're using Apollo. Alternatively, please file a PR if you already have a blog post or a conference talk that you'd like to feature here.