Migrating React Relay from v18 to v19

Relay 19 tightens alias requirements and adds React 19 compatibility.

Key changes

• The @alias directive is required on conditional fragments. Use @dangerously_unaliased_fixme to suppress or run the mark-dangerous-conditional-fragment-spreads codemod.
• Generated JS files use ES module imports by default. Set "eagerEsModules": false in relay.config.json to revert.
• Pre-bundled modules were removed from npm packages.
• Documentation improvements and React 19 support.

Alias enforcement example

Before upgrading:

fragment ItemPreview on Item @include(if: $show) {
  name
}

After upgrade you must add @alias:

fragment ItemPreview on Item @include(if: $show) @alias(localItemPreview) {
  name
}

ES module configuration

The compiler now emits ES modules. To retain CommonJS output set:

{
  "eagerEsModules": false
}

Migration steps

1. Upgrade to ^19.0.0.
2. Run the codemod to mark conditional fragment spreads and update code with @alias as appropriate.
3. Verify your build system supports ES module imports or configure the eagerEsModules flag.
4. Regenerate artifacts with the updated compiler.