GraphQL Fragments

A fragment is the data contract of one component. The component declares the fields it reads in its own fragment, the query above it spreads that fragment, and Apollo's data masking hands the component only those fields. Masking is on everywhere: createApolloClient sets dataMasking: true, and codegen emits masked types (inlineFragmentTypes: "mask"). Reading a field the fragment didn't select is therefore a type error, and the field is undefined at runtime. This page is the one home for our fragment rules; for how useFragment and masking work in general, see Apollo's fragments docs. A screen is a tree of components, and every one of them needs data. There are two obvious ways to fetch it, and both go wrong as the tree grows: A component-owned fragment avoids both. Each component declares the fields it reads next to its code, a parent spreads its children's fragments into its own, and the route's one query composes them all. The screen is fetched in one round trip, and a component's data requirements change in one file. When a child needs another field, only its fragment changes. The sections below show the mechanics; a component that can't be served this way runs its own query (When a component runs its own query). The examples on this page are illustrative: ChatroomsView, ChatroomListItem, ChatroomHeader and ChatroomLabel are not components in this repo. Masking is what keeps the coupling from coming back through the side door. Without it, a parent can read a field that only its child's fragment selected, and nothing says so. Apollo's data masking docs tell the story with a Posts list that filters on publishedAt, a field that only the PostDetails child's fragment selected. When PostDetails stops using publishedAt and drops it from its fragment, Posts still depends on it, finds it missing, and renders no posts. Apollo calls this "an implicit dependency between components". The same thing here: ChatroomsView filters chatrooms on resolved, which only ChatroomListItem_chatroom selects, and the day that fragment drops resolved the list silently empties. Nothing in ChatroomListItem looks wrong, so its own tests keep passing. We mask in two places, and each catches something the other doesn't: Both layers lift together for a fragment spread with @unmask, which is why @unmask needs a reason. To make the parent's dependency explicit and safe instead, add the field to the parent's own fragment or query. Each component gets a fragment in a fragments.graphql next to it: The parent's query spreads its direct child's fragment. It selects id itself, because Apollo needs it to find the entity again and to key the list: There is no #import line: codegen and lint read every document, so a spread of a fragment defined in another file just works. pnpm codegen writes a …FragmentDoc (the document) and a …Fragment type (the type of the fragment's own fields) named after each fragment, next to the .graphql file. For ChatroomListItem_chatroom those are, e.g., ChatroomListItemChatroomFragmentDoc and ChatroomListItemChatroomFragment. A component takes a FragmentType for its prop and opens it with useFragment. Always pass fragmentName (the fragment's Component_prop name) to useFragment, readFragment, writeFragment and watchFragment. A fragment document that spreads a child's fragment holds more than one definition, and Apollo then requires fragmentName, so passing it from the start keeps the call working when someone later adds ...Child: data holds this component's own fields plus a reference to ChatroomLabel_chatroom, which ChatroomLabel opens in the same way. Always pass fragmentName, as Apollo's own examples do, to useFragment, useSuspenseFragment, readFragment, writeFragment, and watchFragment, even when the fragment spreads nothing today; pnpm lint:graphql reports a call that leaves it out. The generated document of a fragment that spreads another holds the child's definition too, so it has more than one fragment in it, and Apollo throws fragmentName must be provided when there is not exactly 1 fragment when it can't tell which one to read. That means adding ...Child to a leaf's fragment later would break its parent's call at runtime, in a file the change never touched. Passing fragmentName works in every case. No lint rule checks it. The route is the only component that calls a query hook: Several parents can spread the same child's fragment: the child owns the fields, and a spread is how a parent includes them. Here ChatroomLabel shows up in a list row and in a page header: Each parent spreads the fragment and hands the opaque reference to <ChatroomLabel chatroom={data} />. Neither reads ChatroomLabel's fields or imports its …FragmentDoc; only ChatroomLabel does, to call useFragment. A change to ChatroomLabel_chatroom reaches every screen that renders it through its own parents' spreads, with no edit to any of them. The Guild's fragments guide shows the same shape: Avatar_UserFragment is spread from both UserListItem_UserFragment and UserProfileHeader_QueryFragment. What the rule forbids is a component importing another component's …FragmentDoc for any purpose, whether to read its fields, call writeFragment or read it by id, which skips the child and brings back the coupling masking removes. pnpm lint:graphql reports a .graphql import from outside the importing file's folder. useFragment reads the fragment from the cache. It never makes a request, and it subscribes to that slice of the cache, so the component re-renders when its own fields change and not when something else in the cache does. It returns { complete, data, missing }: When a component has an id and no parent object (a map marker for a chatroom id, a row that a subscription updates), give useFragment the entity to read: The fragment is still the component's own. Nothing else about the rules changes: the entity has to be in the cache because some query put it there. ChatroomListItemChatroomFragment is the type of the fragment's own fields, without the references to child fragments. Use it for a helper function or a custom hook that takes a component's data after useFragment has opened it. Don't use it as a prop type: a prop is the FragmentType reference the parent passes. The default is a fragment. A component that renders data its parent's query already fetches, or could fetch at no extra cost (a list row, a card, a label, a section of a screen whose entity the screen already loads), declares a Component_prop fragment and reads it with useFragment. Apollo's bundled skill puts it the same way: a page should "generally" have one query, composed from the fragments of the components below it. A component may call a query hook itself when at least one of these is true: A component with its own query is still masked, still reads its own fields, and still passes fragment references to its children. Every fragment rule above applies to it unchanged. Three patterns are worth avoiding. They are guidance only: no lint rule or review agent checks them, because deciding them needs the render tree and the other files. Tests, stories and mocks may call a query hook wherever they need to. A custom hook isn't a component, so the thin-wrapper rule governs it instead. @unmask makes a fragment's fields visible to the parent again, as if there were no masking: It couples the two components, which is what masking exists to prevent, so treat it as an escape hatch: useFragment finds a component's object in the cache by its identity, which is id unless the cache is given keyFields for the type. A type with neither is stored inside its parent and has no entry of its own, so useFragment has nothing to look up: it returns complete: true with the fields missing, and Apollo logs "Could not identify object". A fragment on such a type is rejected by pnpm lint:graphql (axon/fragment-type-has-cache-identity), which reads the schema and packages/data-gql/src/cache-key-fields.json (the types that createPreparedInMemoryCache gives keyFields). The file is validated when it loads: each type maps to a non-empty array of field names that exist on the type, and a typo fails lint with a message that names it. On an interface or a union (see below), every type it can stand for must have an identity, because the object in the cache is one of them. The root types (Query, Mutation, Subscription) are exempt. Masking applies to every request-based API: useQuery, useMutation, useSubscription, client.query, and client.mutate. A mutation result that spreads a fragment is masked in the same way. The cache APIs are never masked. cache.readFragment, cache.writeFragment, cache.updateQuery, and cache.modify see and write whole objects, so a subscription handler can update a fragment's fields directly (see Pub/Sub). GraphQL Cache covers when to update the cache and when to refetch. A fragment on an interface or union selects the shared fields and then the fields of each member. The component that owns it handles each case: When a component's fragment feels too large, extract focused child fragments (one per component that reads them) and spread them back. Do not give each component its own useQuery for data the page already loads: The fix is the structure above: ChatbotStatus_chatroom and LanguageBanner_chatroom fragments, each read with useFragment by its component, spread by the component that renders them, with the page's single query at the top. Breaking a fragment up this way doesn't shrink the payload by itself. It makes each field's owner obvious, so a field is removed when its component stops reading it. Extracting a type from a query result with indexed access ties a component to the query's shape. Give the component a fragment instead: The oxlint rule no-result-type-indexing rejects the indexed form for generated *Query, *Mutation, and *Subscription types. renderWithApollo builds its client with createApolloClient, so tests run with masking on, the same as the app. The factories and mock handlers return whole objects; the client masks them on the way in, so a component test sees exactly what the component would see in production. Render the component that owns the query and assert on the child's output, or give a child a reference from a query result. To put fragment data in the cache directly, use Apollo's client.writeFragment({ fragment, fragmentName, data }) with from: { __typename, id }. A seedFragment helper (CORE-1305) is coming as a thin wrapper over it. The recipe for testing one fragment-owning component on its own is in Testing a Fragment-Owning Component on Its Own. Import from the .graphql file. Vite resolves it to the generated .graphql.ts: The generated document of a fragment holds the fragment and every fragment it spreads, so useFragment, readFragment, watchFragment, and writeFragment find the children. If you see the first error, check that packages/data-gql/src/codegen.ts sets no documentMode (graphQLTag writes only the fragment's own definition) and re-run pnpm codegen. The second means a useFragment, useSuspenseFragment, readFragment, writeFragment or watchFragment call is missing fragmentName: pass the fragment's own name. The Component_prop pattern keeps names unique in practice, because component names are. Generic names like Data or ChatroomData will collide, and the pattern rejects them. The FragmentType and MaybeMasked types only mask when @prepared911/data-gql is part of the TypeScript program. Every generated *.graphql.ts imports it, so a package that uses a generated document gets it automatically. If a package uses @apollo/client without any generated document and reads fragment data, import @prepared911/data-gql once so the types apply. For day-to-day workflow, debugging, and troubleshooting, see the Development Workflow guide.