breaking change in v3.12 with graphql-codegen's fragment masking

[macrozone]

Issue Description

graphql-codegen's client preset popularized the fragment masking approach, so I assume its widely adopted.

Apollo Client v3.12 introduces also data masking with fragments https://www.apollographql.com/blog/more-resilient-code-with-data-masking-in-apollo-client-3-12

however, those two approaches are incompatible, updating an existing codebase to v3.12 will break because the data type of useQuery won't have the correct type anymore.

Apollo doesn't provide a direct solution, instead it's even mentioned here that its incompatbile with the client-preset:

https://www.apollographql.com/docs/react/data/fragments#with-the-client-preset

The documentation suggests, to disable graphql-codegen's fragment masking and use apollo's useFragment hook instead of its own. However, this requires significant changes to existing codebases and is in my opinion a breaking change.

Affected users have to stick with v3.11x.

It would be good if either apollo client or graphql-codegen would provide a more simpler transition. Updating a minor version of apollo client should not lead to such a big breaking change, altough i understand its just the type definitions that are incompatbile.

Link to Reproduction

none

Reproduction Steps

No response

@apollo/client version

3.12.4

[phryneas]

"incompatible" in this case means "you cannot use both methods of fragment masking at the same time", but beyond that, the CodeGen fragment masking works as well - you just have to be aware that their fragment masking has no runtime implications and does not give you any better performance.

What you do have to do is to enable data masking types once, though - we have gotten a lot of complaints from people using the CodeGen default client preset and as a result accidentally turning on data masking without wanting it, so the default is "off" and restores "unmasked" types. (we are getting the feedback from the other side now, though, and might consider changing that default)

in a apollo-client.d.ts:

// This import is necessary to ensure all Apollo Client imports
// are still available to the rest of the application.
import '@apollo/client';

declare module "@apollo/client" {
  interface DataMasking {
    enabled: true;
  }
}

[jerelmiller]

@macrozone I'll see if we can amend the language a bit in the docs to be more specific on what "incompatible" means. @phryneas is right that the incompatibility is more on the runtime behavior than anything else, but the actual type output used for Apollo's data masking is the same as the fragment masking feature in codegen.