From d3261ac0bd4ad06004da4800e2027cac7301784e Mon Sep 17 00:00:00 2001 From: Eddy Nguyen Date: Tue, 24 Mar 2026 23:49:26 +1100 Subject: [PATCH] Update migration guide with Persisted Doc Hash Algorithm and ESM breaking changes (#10653) * Make breaking chnages title consistent * Add breaking changes for persisted doc hash algorithm and ESM deps inclusino * Fix format --- .../operations-and-client-preset-from-5-0.mdx | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/website/src/pages/docs/migration/operations-and-client-preset-from-5-0.mdx b/website/src/pages/docs/migration/operations-and-client-preset-from-5-0.mdx index 40cfd5548e6..1ddc9cec3d7 100644 --- a/website/src/pages/docs/migration/operations-and-client-preset-from-5-0.mdx +++ b/website/src/pages/docs/migration/operations-and-client-preset-from-5-0.mdx @@ -386,14 +386,30 @@ The following utility types have been removed: - `InputMaybe`: used to handle nullability types of Input. Input types are now inlined, so this type is no longer needed. - `MakeOptional`, `MakeMaybe` and `MakeEmpty`: used to handle `preResolveTypes:false`. However, `preResolveTypes` has been removed, so these types are no longer needed. -### 11. Make `unknown` the default type for custom scalars instead of `any` +### 11. `unknown` is the default type for custom scalars instead of `any` Previously, the default custom Scalars type was `any`, which bypassed typechecking. Now, the default type is `unknown` to ensure data is handled carefully by users. -### 12. Make `string | number` the default type for the native `ID` scalar +### 12. `string | number` is the default type for the native `ID` scalar Previously, one set of default Scalar types was shared between client and server plugins via the `typescript` plugin dependency. This meant it was not possible to set the default for client, as it would complicate the server config, and vice versa. See this [PR for more details](https://github.com/dotansimha/graphql-code-generator/pull/9497). Now, the `typescript` plugin is no longer a dependency. So, we can set the default type as `string | number`, which is the correct type for client use cases. For more details on how Scalar coercion works here, please read [The Complete GraphQL Scalar Guide](https://the-guild.dev/graphql/hive/blog/the-complete-graphql-scalar-guide#scalar-value-coercion). + +### 13. client-preset persisted document default hash algorithm is SHA256 + +Previously, the default hash algorithm for persisted documents was `sha1`. + +Now, the default is `sha256`. When using `sha256`, the generated hash conforms to the format defined in the [GraphQL over HTTP spec for persisted document identifiers](https://github.com/graphql/graphql-over-http/blob/52d56fb36d51c17e08a920510a23bdc2f6a720be/spec/Appendix%20A%20--%20Persisted%20Documents.md#sha256-hex-document-identifier). + +### 14. Core plugins have ESM dependencies + +This change mainly impacts plugin maintainers. + +Previously, core plugins were stuck on older dependency versions because ESM-only packages made integration and testing harder for maintainers. + +Now, Node.js 20 support has been dropped, Node.js 22 can load ESM seamlessly at runtime, with no extra configuration. This allows core plugins to adopt dependencies that are ESM-only. + +Plugin maintainers using [Jest](https://jestjs.io/) may still encounter issues. We recommend switching to [Vitest](https://vitest.dev/), which has native ESM support.