Migrating React Relay from v17 to v18

Relay 18 stabilizes several directives and introduces new error-handling features.

Key changes

• Validation of argument types for client-defined fields; can be disabled with disable_full_argument_type_validation.
• @alias now stable, allows accessing fragments via alias properties.
• New directives: @catch, @throwOnFieldError, and support for @semanticNonNull.
• Relay Resolvers can accept a shared context and are no longer experimental starting in 18.1.
• New configuration option noSourceControl to prevent automatic SCM integration.

Using @alias and @catch

Example conditional fragment before migration:

fragment UserPreview on User @include(if: $cond) {
  name
}

The compiler in v18 requires an alias for conditional fragments:

fragment UserPreview on User @include(if: $cond) @alias(localUserPreview) {
  name
}

Handling errors with @catch:

fragment UserProfile on User {
  profilePicture(size: 32) @catch(as: "error")
}

Migration steps

1. Upgrade packages to ^18.0.0 (and later 18.1/18.2 for bug fixes).
2. Review argument types of resolvers and client schema extensions; use the feature flag to disable if needed.
3. Consider adopting @alias for conditional fragments and run the provided codemod.
4. Use @catch and @throwOnFieldError to handle GraphQL errors explicitly.
5. Update Relay Resolver code to handle the new context argument if used.
6. Regenerate artifacts and verify application behavior.