Skip to content

Commit 94314ad

Browse files
phryneasphryneas
committed
start work on the migration guide
1 parent 7f3e3f1 commit 94314ad

2 files changed

Lines changed: 263 additions & 4 deletions

File tree

‎docs/source/_sidebar.yaml‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -117,10 +117,8 @@ items:
117117
href: ./networking/advanced-http-networking
118118
- label: Authentication
119119
href: ./networking/authentication
120-
- label: Migrating
121-
children:
122-
- label: Migrating to Apollo Client 3.0
123-
href: ./migrating/apollo-client-3-migration
120+
- label: Migrating to Apollo Client 4.0
121+
href: ./migrating/apollo-client-4-migration
124122
- label: API Reference
125123
children:
126124
- label: Core

‎docs/source/migrating/apollo-client-4-migration.mdx‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
---
2+
title: Migrating to Apollo Client 4.0
3+
---
4+
5+
This article walks you through migrating your application to Apollo Client 4.0 from a previous installation of Apollo Client 3.14.
6+
7+
<Note>
8+
9+
If you are migrating from older versions of Apollo Client 3, we generally recommend updating to Apollo Client 3.14 first.
10+
Apollo Client 3.14 introduces a lot of deprecations and warnings that will help you to prepare your application for a smooth migration to Apollo Client 4.0.
11+
12+
</Note>
13+
14+
## What’s new in 4.0
15+
16+
- Bundling changes
17+
- Apollo Client 4.0 now has an `exports` field in it's `package.json` for better ESM support
18+
- `@apollo/client/core` and `@apollo/client` are now identical and framework-agnostic. React-related exports are now only available in `@apollo/client/react`.
19+
- Enhanced Error Handling
20+
- network errors are now handled the same way as GraphQL errors and populate the `error` field of a query result
21+
- the throwing behaviour between network errors and GraphQL errors has been unified
22+
- `ApolloError` has been removed. A number of new error classes has been introduced, and external errors are now passed through as-is without wrapping them, which allows for easier debugging.
23+
- TypeScript improvements
24+
- APIs like `client.query` or `useQuery` that accept variables in options will now require the variables to be passed in if any option is non-optional.
25+
- return types are more precise, taking options into account - if you pass in the `returnPartialData` option, `data` on the return object will be `DeepPartial<TData>`
26+
- added a new `dataState` property that contains information about the state of the `data` property of a return value. This property can be used to narrow down the type of `data`.
27+
- most types are now colocated within the API that they relate to, so it is much easier to find the right type for the right situation.
28+
Some examples:
29+
- `FetchResult` is now `ApolloLink.Result`
30+
- `ApolloClientOptions` is now `ApolloClient.Options`
31+
- `QueryOptions` is now `ApolloClient.QueryOptions`
32+
- `ApolloQueryResult` is now `ObservableQuery.Result`
33+
- `QueryHookOptions` is now `useQuery.Options`
34+
- `QueryResult` is now `useQuery.Result`
35+
- `LazyQueryResult` is now `useLazyQuery.Result`
36+
- some core types like types for `DataMasking` or types representing the that `dataState` narrows down to can now be overwritten.
37+
- Local State changes
38+
- The local resolver implementation is now a pluggable `LocalState` class to save on bundle size for everyone who doesn't use it.
39+
- Many improvements and bug fixes in the new `LocalState` implementation
40+
- The `Observable` implementation has been changed to `rxjs`.
41+
- The incremental delivery implementation has been made pluggable, so in the future we can support multiple different versions of the incremental delivery protocol.
42+
- For a full list of changes, please see the [changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md).
43+
44+
## Installation
45+
46+
> **WARNING:** Apollo Client 4.0 is a major-version release that includes **breaking changes**. If you are updating an existing application to use Apollo Client 4.0, please see the [changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md) for details about these changes.
47+
48+
Install Apollo Client 4.0 along with it's peer dependencies with the following command:
49+
50+
```
51+
npm install @apollo/client graphql rxjs
52+
```
53+
54+
-------- old guide from here
55+
56+
## Updating imports
57+
58+
The `@apollo/client` library includes functionality that previously required installing additional packages. As part of migrating to Apollo Client 3.0, follow the instructions below for each library your application currently uses.
59+
60+
> To simplify the process of converting your `import` declarations from older packages to `@apollo/client`, we provide an automated [transform](https://github.com/apollographql/apollo-client/tree/main/scripts/codemods/ac2-to-ac3) based on [`jscodeshift`](https://www.npmjs.com/package/jscodeshift). Note that this transform merely moves `import` specifiers between `import` declarations, without checking for proper usage of the imported values. Since the transform cannot take care of everything, pay close attention to any errors produced by TypeScript or your bundling tools, and be sure to verify all changes made by the transform. A more detailed list of caveats can be found in the [`README.md`](https://github.com/apollographql/apollo-client/tree/main/scripts/codemods/ac2-to-ac3#known-limitations).
61+
62+
### @apollo/react-hoc and @apollo/react-components
63+
64+
React Apollo HOC and component functionality is now included in the `@apollo/client` package:
65+
66+
```js
67+
import { Query, Mutation, Subscription } from "@apollo/client/react/components";
68+
import { graphql } from "@apollo/client/react/hoc";
69+
```
70+
71+
As part of migrating, we recommend removing all `@apollo/react-hoc` and `@apollo/react-components` dependencies.
72+
73+
### @apollo/react-hooks
74+
75+
All `@apollo/react-hooks` functionality is included in the `@apollo/client` package. For example:
76+
77+
```js
78+
import { ApolloProvider, useQuery, useApolloClient } from "@apollo/client";
79+
```
80+
81+
As part of migrating, we recommend removing all `@apollo/react-hooks` dependencies.
82+
83+
**Breaking Changes:**
84+
85+
- `useQuery` [no longer maintains the previously fetched results](https://github.com/apollographql/apollo-client/pull/6566) in its `data` result when loading new data. Instead, when new data is being loaded (i.e. `loading` === `true`) the `data` result of `useQuery` is set to `undefined`. Use the `previousData` result as a bridge to the old v2 behavior.
86+
- `refetch` functionality of `useQuery` [was broken in 3.5.x until it was fixed in 3.5.8](https://github.com/apollographql/apollo-client/issues/9101). Previous to this version, if the `skip: true` option was used, `refetch` would always be `undefined`.
87+
88+
### @apollo/react-ssr
89+
90+
React Apollo’s SSR utilities (like `getDataFromTree`, `getMarkupFromTree`, and `renderToStringWithData`) are included in the `@apollo/client` package. Access them via `@apollo/client/react/ssr`:
91+
92+
```js
93+
import { renderToStringWithData } from "@apollo/client/react/ssr";
94+
```
95+
96+
As part of migrating, we recommend removing all `@apollo/react-ssr` dependencies.
97+
98+
### @apollo/react-testing
99+
100+
React Apollo’s testing utilities (like `MockedProvider`) are included in the `@apollo/client` package. Access them via `@apollo/client/testing`:
101+
102+
```js
103+
import { MockedProvider } from "@apollo/client/testing";
104+
```
105+
106+
As part of migrating, we recommend removing all `@apollo/react-testing` dependencies.
107+
108+
### apollo-boost
109+
110+
The Apollo Boost project is now retired, because Apollo Client 3.0 provides a similarly straightforward setup. We recommend removing all `apollo-boost` dependencies and modifying your `ApolloClient` constructor as needed.
111+
112+
### apollo-client
113+
114+
With Apollo Client 3.0, the `apollo-client` package is retired in favor of `@apollo/client`. As part of migrating, remove all `apollo-client` dependencies.
115+
116+
### apollo-link and apollo-link-http
117+
118+
All `apollo-link`, `apollo-link-http`, and `apollo-link-http-common` functionality is included in the `@apollo/client` package. For example:
119+
120+
```js
121+
import { ApolloLink, HttpLink, from, split, execute } from "@apollo/client";
122+
```
123+
124+
As part of migrating, we recommend removing all `apollo-link`, `apollo-link-http`, and `apollo-link-http-common` dependencies.
125+
126+
If you want to configure your own link chain, the `ApolloClient` constructor still accepts a link option. Otherwise, the `ApolloClient` constructor now also supports `uri`, `headers`, and `credentials` options. For example:
127+
128+
```js
129+
const client = new ApolloClient({
130+
cache,
131+
uri: 'http://localhost:4000/graphql',
132+
headers: {
133+
authorization: localStorage.getItem('token') || '',
134+
'client-name': 'Space Explorer [web]',
135+
'client-version': '1.0.0',
136+
},
137+
...
138+
});
139+
```
140+
141+
These options are passed into a new `HttpLink` instance behind the scenes, which `ApolloClient` is then configured to use.
142+
143+
### apollo-link-\*
144+
145+
The separate `apollo-link-*` packages, that were previously maintained in the https://github.com/apollographql/apollo-link repo, have been merged into the Apollo Client project. These links now have their own nested `@apollo/client` entry points. Imports should be updated as follows:
146+
147+
- `apollo-link-batch` is now `@apollo/client/link/batch`
148+
- `apollo-link-batch-http` is now `@apollo/client/link/batch-http`
149+
- `apollo-link-context` is now `@apollo/client/link/context`
150+
- `apollo-link-error` is now `@apollo/client/link/error`
151+
- `apollo-link-retry` is now `@apollo/client/link/retry`
152+
- `apollo-link-schema` is now `@apollo/client/link/schema`
153+
- `apollo-link-ws` is now `@apollo/client/link/ws`
154+
155+
It is important to note that Apollo Client 3 no longer allows `@client` fields to be passed through a Link chain. While Apollo Client 2 made it possible to intercept `@client` fields in Link's like `apollo-link-state` and `apollo-link-schema`, Apollo Client 3 enforces that `@client` fields are local only. This helps ensure Apollo Client's local state story is easier to understand, and prevents unwanted fields from accidentally ending up in network requests ([PR #5982](https://github.com/apollographql/apollo-client/pull/5982)).
156+
157+
### graphql-anywhere
158+
159+
The `graphql-anywhere` package’s functionality is no longer included with Apollo Client. You can continue to use the `graphql-anywhere` package, but Apollo no longer uses it and will not actively support it moving forward.
160+
161+
### graphql-tag
162+
163+
The `@apollo/client` package includes `graphql-tag` as a dependency and re-exports `gql`. To simplify your dependencies, we recommend importing gql from `@apollo/client` and removing all `graphql-tag` dependencies.
164+
165+
### react-apollo
166+
167+
`react-apollo` v3 is an umbrella package that re-exports the following packages:
168+
169+
- `@apollo/react-common`
170+
- `@apollo/react-hooks`
171+
- `@apollo/react-components`
172+
- `@apollo/react-hoc`
173+
- `@apollo/react-ssr`
174+
- `@apollo/react-testing`
175+
176+
The `react-apollo` package has been deprecated, and the functionality offered by each of the above packages can now be accessed from `@apollo/client` directly:
177+
178+
- `@apollo/react-hooks` -> now available directly from `@apollo/client`
179+
- `@apollo/react-components` -> now available from `@apollo/client/react/components`
180+
- `@apollo/react-hoc` -> now available from `@apollo/client/react/hoc`
181+
- `@apollo/react-ssr` -> now available from `@apollo/client/react/ssr`
182+
- `@apollo/react-testing` -> now available from `@apollo/client/testing`
183+
184+
## Using individual components of Apollo Client 3
185+
186+
Apollo Client 3.0 provides multiple entry points for you to import from. If you only use a particular part of Apollo Client’s functionality, you can import that functionality from its corresponding entry point. By doing so, modern bundlers can omit the remainder of the `@apollo/client` package from your bundle and reduce its size considerably.
187+
188+
### Using Apollo Client without React
189+
190+
Apollo Client 3.0 includes built-in support for React hooks, but it absolutely still supports non-React view layers. To use Apollo Client 3.0 with Vue, Angular, or another view layer of your choosing, import `ApolloClient` from the `@apollo/client/core` entry point:
191+
192+
```js
193+
import { ApolloClient } from "@apollo/client/core";
194+
```
195+
196+
### Using apollo-utilities without the rest of Apollo Client
197+
198+
The `apollo-utilities` package has been removed, but you can access the utilities themselves from the `@apollo/client/utilities` entry point:
199+
200+
```js
201+
import { isReference, isInlineFragment } from "@apollo/client/utilities";
202+
```
203+
204+
### Using apollo-cache and/or apollo-cache-inmemory without the rest of Apollo Client
205+
206+
The `apollo-cache` and `apollo-cache-inmemory` packages have been removed, but if you're interested in using Apollo Client's cache by itself, you can access their contents with the `@apollo/client/cache` entry point:
207+
208+
```js
209+
import { ApolloCache, InMemoryCache } from "@apollo/client/cache";
210+
```
211+
212+
## Cache improvements
213+
214+
Apollo Client 3.0 introduces powerful improvements to its caching system. Most of these improvements are backward compatible, so most applications will continue to work without any changes to caching logic. However, we highly recommend learning more about the capabilities of the Apollo Client 3.0 cache.
215+
216+
- [Configuring the cache](../caching/cache-configuration/)
217+
- [Interacting with cached data](../caching/cache-interaction/)
218+
219+
### Breaking cache changes
220+
221+
The following cache changes are **not** backward compatible. Take them into consideration before you upgrade to Apollo Client 3.0.
222+
223+
- By default, the `InMemoryCache` no longer merges the fields of two objects unless those objects have the same unique identifier and that identifier is present in both objects. Additionally, the values of fields with the same name are no longer merged recursively by default. You can define a custom `merge` function for a field to handle both of these changes for a particular field. You can read more about these changes in [Merging non-normalized objects](../caching/cache-field-behavior/#merging-non-normalized-objects). ([PR #5603](https://github.com/apollographql/apollo-client/pull/5603)).
224+
- All cache results are now frozen/immutable, as promised in the [Apollo Client 2.6 blog post](https://blog.apollographql.com/whats-new-in-apollo-client-2-6-b3acf28ecad1) ([PR #5153](https://github.com/apollographql/apollo-client/pull/5153)).
225+
- `FragmentMatcher`, `HeuristicFragmentMatcher`, and `IntrospectionFragmentMatcher` have all been removed. We recommend using the `InMemoryCache`’s `possibleTypes` option instead. For more information, see [Defining possibleTypes manually](../data/fragments/#defining-possibletypes-manually) ([PR #5073](https://github.com/apollographql/apollo-client/pull/5073)).
226+
- The internal representation of normalized data in the cache has changed. If you’re using `apollo-cache-inmemory`’s public API, then these changes shouldn’t impact you. If you are manipulating cached data directly instead, review [PR #5146](https://github.com/apollographql/apollo-client/pull/5146) for details.
227+
- `client|cache.writeData` have been fully removed. `client|cache.writeQuery`, `client|cache.writeFragment`, and/or `cache.modify` can be used to update the cache. For example:
228+
229+
```js
230+
client.writeData({
231+
data: {
232+
cartItems: [],
233+
},
234+
});
235+
```
236+
237+
can be converted to:
238+
239+
```js
240+
client.writeQuery({
241+
query: gql`
242+
query GetCartItems {
243+
cartItems
244+
}
245+
`,
246+
data: {
247+
cartItems: [],
248+
},
249+
});
250+
```
251+
252+
For more details around why `writeData` has been removed, see [PR #5923](https://github.com/apollographql/apollo-client/pull/5923).
253+
254+
- `cache-and-network` fetch policy now initiates a network request whenever there are cache updates that affect the query, and is no longer limited to the first time the query is run. In order to recreate the default behavior from `2.x.x`, please configure a `nextFetchPolicy` (available in versions `>=3.1.0`). For example:
255+
256+
```js
257+
const { loading, error, data } = useQuery(GET_ALL_TODOS, {
258+
fetchPolicy: "cache-and-network",
259+
nextFetchPolicy: "cache-first",
260+
});
261+
```

0 commit comments

Comments
 (0)