Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update README links to point to non-experimental hooks links #309

Merged
merged 1 commit into from
Jun 5, 2024
Merged

Update README links to point to non-experimental hooks links #309

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions packages/experimental-nextjs-app-support/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
# Apollo Client support for the Next.js App Router

> ❗️ This package is experimental.<br/>
> Generally it should work well, you might run into race conditions when your Client Component is still rendering in SSR, and already making overlapping queries on the browser.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This whitespace was unfortunately very important - in GitHub markdown, two spaces at a line end mark a <br/> tag 😬

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wow, thats quite a choice by them. It looks like \ also works to add line breaks, would you be okay with a PR that uses those as the more explicit option to get the docs back to the way they were?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jer-k yes! Apologies on my part for not realizing the spaces were intentional. I've got a command to remove trailing whitespace when I save in my editor, so I think the more explicit \ would be welcome :).

Feel free to open a new PR if you'd like, otherwise I can tackle this later today.

> This cannot be addressed from our side, but would need API changes in Next.js or React itself.
> Generally it should work well, you might run into race conditions when your Client Component is still rendering in SSR, and already making overlapping queries on the browser.
> This cannot be addressed from our side, but would need API changes in Next.js or React itself.
> If you do not use suspense in your application, this will not be a problem to you.

| ☑️ Apollo Client User Survey |
Expand Down Expand Up @@ -41,8 +41,8 @@ npm install @apollo/client@latest @apollo/experimental-nextjs-app-support

## Usage

> ❗️ **We do handle "RSC" and "SSR" use cases as completely separate.**
> You should generally try not to have overlapping queries between the two, as all queries made in SSR can dynamically update in the browser as the cache updates (e.g. from a mutation or another query), but queries made in RSC will not be updated in the browser - for that purpose, the full page would need to rerender. As a result, any overlapping data would result in inconsistencies in your UI.
> ❗️ **We do handle "RSC" and "SSR" use cases as completely separate.**
> You should generally try not to have overlapping queries between the two, as all queries made in SSR can dynamically update in the browser as the cache updates (e.g. from a mutation or another query), but queries made in RSC will not be updated in the browser - for that purpose, the full page would need to rerender. As a result, any overlapping data would result in inconsistencies in your UI.
> So decide for yourself, which queries you want to make in RSC and which in SSR, and don't have them overlap.

### In RSC
Expand Down Expand Up @@ -153,10 +153,10 @@ export default function RootLayout({
}
```

> ☝️ This will work even if your layout is a React Server Component and will also allow the children of the layout to be React Server Components.
> ☝️ This will work even if your layout is a React Server Component and will also allow the children of the layout to be React Server Components.
> It just makes sure that all Client Components will have access to the same Apollo Client instance, shared through the `ApolloNextAppProvider`.

If you want to make the most of the streaming SSR features offered by React & the Next.js App Router, consider using the [`useSuspenseQuery`](https://www.apollographql.com/docs/react/api/react/hooks-experimental/#using-usesuspensequery_experimental) and [`useFragment`](https://www.apollographql.com/docs/react/api/react/hooks-experimental/#using-usefragment_experimental) hooks.
If you want to make the most of the streaming SSR features offered by React & the Next.js App Router, consider using the [`useSuspenseQuery`](https://www.apollographql.com/docs/react/api/react/hooks/#usesuspensequery) and [`useFragment`](https://www.apollographql.com/docs/react/api/react/hooks/#usefragment) hooks.

### Preloading data in RSC for usage in Client Components

Expand Down Expand Up @@ -192,7 +192,7 @@ export function ClientChild() {
```

> [!TIP]
> The `Suspense` boundary here is optional and only for demonstration purposes to show that something suspenseful is going on.
> The `Suspense` boundary here is optional and only for demonstration purposes to show that something suspenseful is going on.
> Place `Suspense` boundaries at meaningful places in your UI, where they give your users the best user experience.

This example will fetch a query in RSC, and then transport the data into the Client Component cache.
Expand Down Expand Up @@ -236,7 +236,7 @@ export function ClientChild({ queryRef }: { queryRef: QueryRef<TQueryData> }) {
```

> [!TIP]
> The `Suspense` boundary here is optional and only for demonstration purposes to show that something suspenseful is going on.
> The `Suspense` boundary here is optional and only for demonstration purposes to show that something suspenseful is going on.
> Place `Suspense` boundaries at meaningful places in your UI, where they give your users the best user experience.

#### Caveat
Expand All @@ -258,7 +258,7 @@ afterEach(resetApolloClientSingletons);
## Handling Multipart responses in SSR

Generally, `useSuspenseQuery` will only suspend until the initial response is received.
In most cases, you get a full response, but if you use multipart response features like the `@defer` directive, you will only get a partial response.
In most cases, you get a full response, but if you use multipart response features like the `@defer` directive, you will only get a partial response.
Without further handling, your component will now render with partial data - but the request will still keep running in the background. This is a worst-case scenario because your server will have to bear the load of that request, but the client will not get the complete data anyways.<br/>
To handle this, you can apply one of two different strategies:

Expand Down