GraphQL Fragments

A fragment is the data contract of one component. The component declares the fields it reads in its own fragment, the route's query spreads that fragment, and Apollo's data masking hands the component only those fields. A component can't read data it didn't ask for, so a parent's query can't quietly start to depend on a child's fields, or the other way around.

Masking is on everywhere: createApolloClient sets dataMasking: true, and codegen emits masked types (inlineFragmentTypes: "mask"). The generated types and the runtime data agree, so a field that isn't in a component's fragment is a type error and also undefined at runtime.

Each component gets a fragment in a fragments.graphql next to it:

The query root 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:

data holds this component's own fields plus a reference to ChatroomLabel_chatroom, which ChatroomLabel opens in the same way. The route is the only component that calls a query hook:

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 route's 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.

A query root is the component that owns a screen's request:

Everything below a query root declares a fragment and reads it with useFragment. A component that calls useQuery itself works only where it is mounted with no parent query, and it makes a request of its own for data that its parent was already going to fetch. The repo/graphql review agent asks about a query hook added in a component that is clearly a leaf from its path alone: a file under a components/ directory (other than exposes/), or one named …Card, …Item, …Row, …Badge, …Popup, …Button, …Label, …Tile, or …Pin. It can't see the render tree, so a leaf with another name is caught in review.

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:

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).

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:

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 route'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 query root and assert on the child's output, or give a child a reference from a query result.

Import from the .graphql file. Vite resolves it to the generated .graphql.ts:

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.