Rework fragment docs #12155

jerelmiller · 2024-11-21T19:51:03Z

This PR does not yet contain docs on data masking, however this does make some tweaks to the existing fragments doc to make fragment colocation more prevalent and recommended. This should setup the data masking sections nicely.

svc-apollo-docs · 2024-11-21T19:51:07Z

✅ Docs Preview Ready

No new or changed pages found.

changeset-bot · 2024-11-21T19:51:07Z

⚠️ No Changeset found

Latest commit: db866e2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

pkg-pr-new · 2024-11-21T19:51:58Z

npm i https://pkg.pr.new/@apollo/client@12155

commit: db866e2

github-actions · 2024-11-21T19:52:21Z

size-limit report 📦

Path	Size
dist/apollo-client.min.cjs	40.64 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs"	50.8 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs" (production)	47.68 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js"	36.15 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js" (production)	33.56 KB (0%)
import { ApolloProvider } from "dist/react/index.js"	1.26 KB (0%)
import { ApolloProvider } from "dist/react/index.js" (production)	1.24 KB (0%)
import { useQuery } from "dist/react/index.js"	5.21 KB (0%)
import { useQuery } from "dist/react/index.js" (production)	4.3 KB (0%)
import { useLazyQuery } from "dist/react/index.js"	5.71 KB (0%)
import { useLazyQuery } from "dist/react/index.js" (production)	4.78 KB (0%)
import { useMutation } from "dist/react/index.js"	3.62 KB (0%)
import { useMutation } from "dist/react/index.js" (production)	2.85 KB (0%)
import { useSubscription } from "dist/react/index.js"	4.43 KB (0%)
import { useSubscription } from "dist/react/index.js" (production)	3.48 KB (0%)
import { useSuspenseQuery } from "dist/react/index.js"	5.51 KB (0%)
import { useSuspenseQuery } from "dist/react/index.js" (production)	4.17 KB (0%)
import { useBackgroundQuery } from "dist/react/index.js"	5.01 KB (0%)
import { useBackgroundQuery } from "dist/react/index.js" (production)	3.66 KB (0%)
import { useLoadableQuery } from "dist/react/index.js"	5.09 KB (0%)
import { useLoadableQuery } from "dist/react/index.js" (production)	3.74 KB (0%)
import { useReadQuery } from "dist/react/index.js"	3.42 KB (0%)
import { useReadQuery } from "dist/react/index.js" (production)	3.36 KB (0%)
import { useFragment } from "dist/react/index.js"	2.37 KB (0%)
import { useFragment } from "dist/react/index.js" (production)	2.31 KB (0%)

netlify · 2024-11-21T19:52:32Z

✅ Deploy Preview for apollo-client-docs ready!

Name	Link
🔨 Latest commit	`8a8b633`
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-client-docs/deploys/673f8f2a3e0fe50008a990e1
😎 Deploy Preview	https://deploy-preview-12155--apollo-client-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify · 2024-11-21T19:53:50Z

✅ Deploy Preview for apollo-client-docs ready!

Name	Link
🔨 Latest commit	`cc777a5`
🔍 Latest deploy log	https://app.netlify.com/sites/apollo-client-docs/deploys/6744e261547c8e0008045970
😎 Deploy Preview	https://deploy-preview-12155--apollo-client-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

jerelmiller · 2024-11-21T19:54:34Z

docs/source/data/fragments.mdx

@@ -45,15 +45,15 @@ If we later _change_ which fields are included in the `NameParts` fragment, we a

 ## Example usage


I made these changes here to try and move away from the notion that fragments should only be used as a DRY tool and instead should be combined with components. While it can be used for DRY, the composition unit should be the component itself rather than the fragment.

jerelmiller · 2024-11-21T20:57:41Z

docs/source/data/fragments.mdx

 ```

 After you define a fragment in a child component, the _parent_ component can refer to it in its _own_ colocated fragments, like so:

 ```js title="FeedEntry.jsx"
-FeedEntry.fragments = {


I'm making a bold choice and moving away from this .fragments pattern that we've had in our docs for so long for a couple reasons:

Exports are fairly typical

Some React component TypeScript types (i.e. React.FC or forwardRef) complain when you try and add static properties on them. This avoids that issue.

Data masking will require these fragments to be used with useFragment. Its much more natural to use a variable than the static property:

useFragment({ fragment: FeedEntryFragment }) // vs useFragment({ fragment: FeedEntry.fragments.entry, })

jerelmiller · 2024-11-21T20:58:50Z

docs/source/data/fragments.mdx

 import { gql } from '@apollo/client';

-export const CORE_COMMENT_FIELDS = gql`
-  fragment CoreCommentFields on Comment {
+export const COMMENT_FRAGMENT = gql`


I'm noticing some of our examples use screaming snake case for variables that are assigned fragments, but others use PascalCase. Should we standardize in our docs?

+1 for being consistent with style, no opinion on which one is better

+1 on agreeing on a convention and not having a preference.

LMK what you decide on and I can add it to our style guide!

I went ahead and settled for SCREAMING_SNAKE_CASE in this doc, specifically to avoid a conflicting name with a TypeScript type of the same name.

For example,

import type { CommentFragment } from './path/to/gql/types.ts'; // Oops we have a conflicting name with the imported type! const CommentFragment = gql` fragment CommentFragment on Comment { # ... } `

This allows us to reuse the "comment fragment" name without the conflict and avoids the need to get creative either by aliasing the import or coming up with a new convention on the variable name itself.

Hope this clarifies it!

jerelmiller · 2024-11-21T20:59:39Z

docs/source/data/fragments.mdx


-Starting in Apollo Client 3.7, fragments can be registered with your `InMemoryCache` so that they can be referred to by name in any query or `InMemoryCache` operation (such as `cache.readFragment`, `cache.readQuery` and `cache.watch`) without needing to interpolate their declarations.
+Starting in Apollo Client 3.7, fragments can be registered with your `InMemoryCache` instance so that they can be referred to by name in any query or `InMemoryCache` operation (such as `cache.readFragment`, `cache.readQuery` and `cache.watch`) without needing to interpolate their declarations.


Since I've added the MinVersion tag, do we need to keep "Starting in Apollo Client 3.7" or should I get rid of it?

I think we can get rid of it 🔪

jerelmiller · 2024-11-21T21:08:40Z

docs/source/data/fragments.mdx


 Consider the following view hierarchy for an app:

 ```
 FeedPage
-└── Feed


I got rid of this intermediate Feed component in the example because its not mentioned anywhere and I wanted to add the note about fragments only being used by their parent.

bignimbus

LGTM - added a few thoughts and a suggestion!

bignimbus · 2024-11-22T19:58:27Z

docs/source/data/fragments.mdx

 import { gql } from '@apollo/client';

-export const CORE_COMMENT_FIELDS = gql`
-  fragment CoreCommentFields on Comment {
+export const COMMENT_FRAGMENT = gql`


+1 for being consistent with style, no opinion on which one is better

bignimbus · 2024-11-22T19:59:25Z

docs/source/data/fragments.mdx


-Starting in Apollo Client 3.7, fragments can be registered with your `InMemoryCache` so that they can be referred to by name in any query or `InMemoryCache` operation (such as `cache.readFragment`, `cache.readQuery` and `cache.watch`) without needing to interpolate their declarations.
+Starting in Apollo Client 3.7, fragments can be registered with your `InMemoryCache` instance so that they can be referred to by name in any query or `InMemoryCache` operation (such as `cache.readFragment`, `cache.readQuery` and `cache.watch`) without needing to interpolate their declarations.


I think we can get rid of it 🔪

docs/source/data/fragments.mdx

Meschreiber

Just some suggestions for clarity! I dig bumping up the colocation bit (which was the part I focused on when reviewing.)

Tomorrow I'll make sure that the mermaid diagram can render!

Meschreiber · 2024-11-25T23:36:36Z

docs/source/data/fragments.mdx

 import { gql } from '@apollo/client';

-export const CORE_COMMENT_FIELDS = gql`
-  fragment CoreCommentFields on Comment {
+export const COMMENT_FRAGMENT = gql`


+1 on agreeing on a convention and not having a preference.

LMK what you decide on and I can add it to our style guide!

docs/source/data/fragments.mdx

Co-authored-by: Maria Elisabeth Schreiber <[email protected]>

jerelmiller requested a review from a team as a code owner November 21, 2024 19:51

jerelmiller added the 📝 documentation label Nov 21, 2024

jerelmiller modified the milestones: 3.12, Data masking Nov 21, 2024

jerelmiller commented Nov 21, 2024

View reviewed changes

jerelmiller force-pushed the jerel/rework-fragment-docs branch from f208671 to 4506df8 Compare November 21, 2024 20:53

jerelmiller commented Nov 21, 2024

View reviewed changes

jerelmiller requested review from bignimbus and phryneas November 21, 2024 21:10

bignimbus reviewed Nov 22, 2024

View reviewed changes

jerelmiller added 10 commits November 25, 2024 15:42

Add additional sentence in fragment doc

87977f7

Update example to use fragments in terms of components

faf70ac

Convert fragments page to mdx file

f182988

Add section on lazy registering fragments

c7a51c5

Rework section on colocated fragments

64bb11c

Replace unions and interfaces link with graphql.com reference

e14325d

Tweak section for unions and interfaces

1001764

Remove note about possibleTypes for 3.0

444ded2

Tweak intro sentence in manual possible types

ba9abde

Minor tweak to manual types

2a2b8e1

jerelmiller added 16 commits November 25, 2024 15:42

Add section on GraphQL Codegen with with possibleTypes

b15a3f0

Tweak note on experimental version

d903d37

Tweak useFragment section

75f9fba

Tweak intro sentence

b75556b

Ensure code languages match their filename

79bd01e

Use mermaid diagram for hierarchy

58d2942

Remove unneeded prefix about version

aaaa966

Add note about fragments

2972f02

Move fragment definition to the bottom

7c7cca8

Rename query in example

7a5666d

Remove export on the query

6d72bab

Fix highlighting

da61991

Tweak sentence on note about client preset

972ce05

Tweak again

9d65709

Use screaming snake case for all fragments

3f9dceb

Tweak comment

b36dd77

jerelmiller force-pushed the jerel/rework-fragment-docs branch from cc777a5 to b36dd77 Compare November 25, 2024 22:42

Meschreiber approved these changes Nov 26, 2024

View reviewed changes

github-actions bot added the auto-cleanup 🤖 label Nov 26, 2024

jerelmiller and others added 9 commits November 25, 2024 22:05

Improve description of fragment

506bd9d

Co-authored-by: Maria Elisabeth Schreiber <[email protected]>

Change how fragments are included and remove the extra blockquote

af38d4d

Tweak how fragment changes are described

2a0ffef

Co-authored-by: Maria Elisabeth Schreiber <[email protected]>

Remove passive voice

702157a

Improve verbiage throughout

f2706d6

Co-authored-by: Maria Elisabeth Schreiber <[email protected]>

Tweak statement about extra fields

c126475

Tweak section on fragment colocation

f0945d7

Merge branch 'release-3.12' into jerel/rework-fragment-docs

97da52c

Remove unneeded usage of we

db866e2

jerelmiller merged commit f2c75dd into release-3.12 Nov 26, 2024
42 of 46 checks passed

jerelmiller deleted the jerel/rework-fragment-docs branch November 26, 2024 16:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rework fragment docs #12155

Rework fragment docs #12155

jerelmiller commented Nov 21, 2024

svc-apollo-docs commented Nov 21, 2024 •

edited

Loading

changeset-bot bot commented Nov 21, 2024 •

edited

Loading

pkg-pr-new bot commented Nov 21, 2024 •

edited

Loading

github-actions bot commented Nov 21, 2024 •

edited

Loading

netlify bot commented Nov 21, 2024

netlify bot commented Nov 21, 2024 •

edited

Loading

jerelmiller Nov 21, 2024

jerelmiller Nov 21, 2024

jerelmiller Nov 21, 2024

bignimbus Nov 22, 2024

Meschreiber Nov 25, 2024

jerelmiller Nov 26, 2024

jerelmiller Nov 21, 2024

bignimbus Nov 22, 2024

jerelmiller Nov 21, 2024

bignimbus left a comment

bignimbus Nov 22, 2024

bignimbus Nov 22, 2024

Meschreiber left a comment

Meschreiber Nov 25, 2024

		@@ -45,15 +45,15 @@ If we later _change_ which fields are included in the `NameParts` fragment, we a

		## Example usage


		Starting in Apollo Client 3.7, fragments can be registered with your `InMemoryCache` so that they can be referred to by name in any query or `InMemoryCache` operation (such as `cache.readFragment`, `cache.readQuery` and `cache.watch`) without needing to interpolate their declarations.
		Starting in Apollo Client 3.7, fragments can be registered with your `InMemoryCache` instance so that they can be referred to by name in any query or `InMemoryCache` operation (such as `cache.readFragment`, `cache.readQuery` and `cache.watch`) without needing to interpolate their declarations.

Rework fragment docs #12155

Rework fragment docs #12155

Conversation

jerelmiller commented Nov 21, 2024

svc-apollo-docs commented Nov 21, 2024 • edited Loading

✅ Docs Preview Ready

changeset-bot bot commented Nov 21, 2024 • edited Loading

⚠️ No Changeset found

pkg-pr-new bot commented Nov 21, 2024 • edited Loading

github-actions bot commented Nov 21, 2024 • edited Loading

size-limit report 📦

netlify bot commented Nov 21, 2024

✅ Deploy Preview for apollo-client-docs ready!

netlify bot commented Nov 21, 2024 • edited Loading

✅ Deploy Preview for apollo-client-docs ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bignimbus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Meschreiber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

svc-apollo-docs commented Nov 21, 2024 •

edited

Loading

changeset-bot bot commented Nov 21, 2024 •

edited

Loading

pkg-pr-new bot commented Nov 21, 2024 •

edited

Loading

github-actions bot commented Nov 21, 2024 •

edited

Loading

netlify bot commented Nov 21, 2024 •

edited

Loading