TL;DR

Relay now correctly includes TypeScript definitions in its published packages, enabling better type safety and developer experience for TypeScript users.

New

• Added a --noWatchman CLI flag to the Relay compiler, allowing builds in environments without the Watchman file watching service (system utility).
• Relay now warns when deprecated enum values are used, helping developers prepare for future updates.

Fixes Worth Knowing

• TypeScript definition files are now correctly included in the published NPM package, resolving a regression in the previous release.

TL;DR

The Relay CLI’s --validate command now functions correctly, as a recent change disabling persisted queries has been reverted.

Fixes Worth Knowing

GraphQL payloads lacking a prototype (a blueprint for objects) are now handled correctly, resolving a runtime error. Documentation for compiler configuration and the useSubscription hook (for real-time data) has been improved.

TL;DR

Relay 19.0.0 introduces a requirement for @alias directives on conditional fragments to improve type safety, alongside significant documentation updates and React 19 compatibility.

Breaking

• Fragments conditionally fetched with @skip, @include, or fragment type conditions now require an @alias directive. Use the mark-dangerous-conditional-fragment-spreads codemod to automatically add @dangerously_unaliased_fixme or disable the validation in relay.config.json.
• Relay no longer includes a pre-bundled module, and defaults to ES module imports (configurable via relay.config.json).

New

• Comprehensive documentation overhaul including quick start and production setup guides.
• Support for React 19.

Fixes Worth Knowing

• Fixed issues with usePagination getting stuck in a loading state.
• Resolved problems with observeFragment causing unhandled rejections on network errors.
• Addressed bugs related to caching and incomplete variables for fragment cycles.

Before You Upgrade

• If you use conditional fragments, run npx relay-compiler codemod mark-dangerous-conditional-fragment-spreads to automatically add temporary fixes, or disable the new validation in your relay.config.json.

TL;DR

Relay 18.2.0 introduces Relay Codemods (automated code updates) to simplify API upgrades and adds an experimental hook, usePrefetchableForwardPaginationFragment, for optimized list pagination with prefetching.

Breaking

• Deprecated Feature Flag: GK relay_enable_load_query_request_deduping has been removed.

New

• Relay Codemods: Automate code updates, including marking required aliases and removing unnecessary directives.
• Prefetchable Pagination: An experimental hook simplifies pre-loading paginated list data for improved performance.
• Expanded @catch Directive: Now usable on fragments, queries, mutations, and aliased inline fragments for more flexible error handling.

Fixes Worth Knowing

• Fixed issues with connections and errors, improving data consistency.
• Resolved errors related to field errors on noncompliant lists.
• Corrected issues with resolver imports and dangling artifacts.

Before You Upgrade

• Remove any usage of the GK relay_enable_load_query_request_deduping feature flag from your configuration.

TL;DR

Relay 17 introduces stricter schema validation and significant performance improvements, particularly in editor tooling and compiler speed, but requires potential configuration updates to avoid breaking changes.

Breaking

• Schema Validation: The compiler now enforces spec-compliant schema validation; disable with "disable_schema_validation": true in relay.config.json.
• Edge Type Validation: Validation of typenames used with @prependNode and @appendNode is now enforced; disable with "disable_edge_type_name_validation_on_declerative_connection_directives": { "kind": "enabled" } in relay.config.json.

New

• @alias Directive (Experimental): Allows fragments to appear as fields, enabling optional or required fragment fetching checks.
• Relay Resolvers: Now support defining types that implement interfaces, with full documentation available.

Fixes Worth Knowing

• Fixed issues with mock data generation for deferred fragments and 3D payloads.
• Improved handling of input fields with default values.
• Resolved a bug where unchanged fragments were unnecessarily marked as clean.
• Search on relay.dev and the compiler explorer have been fixed.

Before You Upgrade

• Review your relay.config.json to determine if you need to disable the new schema or edge type validation features.
• If using the VSCode extension, upgrade to version 2.3.0 to benefit from inlay hints.

TL;DR

Relay now supports @preloadable fragments, allowing for more efficient data fetching and improved application performance.

Breaking

• customScalars in single-project config must now be specified as customScalarTypes (configuration option change).

New

• Added support for @preloadable fragments (data fetching optimization).

Fixes Worth Knowing

• Improved handling of nullable models in client-to-client data updates.
• Fixed issues with Suspense and record cleanup during query updates.
• Resolved a pathing issue on Windows.
• Improved Relay compiler diagnostic error logging (developer tooling).

Before You Upgrade

• Update your Relay configuration to use customScalarTypes instead of customScalars.

TL;DR

Relay 15 introduces significant improvements to the developer experience with a new VSCode extension powered by tighter compiler integration, offering features like autocompletion and schema exploration.

Breaking

• The signature of missing field handlers has changed to use ?ReadOnlyRecordProxy instead of Record.
• Flow users: APIs like usePreloadedQuery have been updated for better React and type support.

New

• VSCode Extension: Enhanced editor integration provides features like field reference finding, fragment completions, and schema information within VSCode.
• Experimental Relay Resolvers: A new mechanism for exposing derived and client state data in the graph is under development, with support for defining resolvers per-file and new GraphQL types.
• Support for fragment argument syntax (GraphQL spec proposal).

Fixes Worth Knowing

• Suspense now works correctly with ReactRelayQueryRenderer and client-only fragments using live resolvers.
• Fixed issues with duplicate field validation and incorrect missing field reporting in the compiler.
• Improved type definitions for pagination hooks (usePaginationFragment, etc.).

Before You Upgrade

• If using Flow, review changes to usePreloadedQuery and related APIs to ensure compatibility with the updated React and type integrations.

TL;DR

Relay now supports more advanced GraphQL features like required fields and argument definitions within @inline fragments (complex data fetching) improving flexibility for complex queries.

New

• Support for @required and client-edges for more precise data requests.
• @argumentDefinitions within @inline fragments enable more complex, reusable query logic.
• useClientQuery hook provides a new way to fetch data.

Fixes Worth Knowing

• Improved error messages when using @live (real-time updates) incorrectly.
• VS Code extension now correctly finds references for resolvers.
• Fixed issues with resolvers and incremental mode, ensuring accurate data fetching.

Before You Upgrade

Update your VS Code extension to benefit from the improved resolver reference finding.

TL;DR

Relay now supports parsing resolver definitions directly from GraphQL docblocks (comments), significantly improving developer experience when defining server-side data fetching logic.

Breaking

• React 18 Peer Dependency: Requires React 18 as a peer dependency.
• Resolver Root Fragment Location: Improved error messaging for invalid Relay Resolver root fragments.

New

• Docblock Resolver Parsing: Define resolvers using docblocks within your GraphQL schema for a more streamlined workflow.
• Live Resolvers (Experimental): Introduced a new experimental feature for building real-time, server-sent data updates with "Live Resolvers."

Fixes Worth Knowing

• Provided Variables: Correctly handles provided variables in root operations and split operations.
• Fragment Bugs: Resolved a nested fragment bug and off-by-one errors.
• Typo Handling: Improved code actions and suggestions for fixing typos in fragment and type/interface names.

Before You Upgrade

• Ensure your project is updated to use React 18.
• Be aware that Live Resolvers are experimental and may have breaking changes in future releases.

TL;DR

Relay v13 introduces experimental Typesafe Updaters (a new way to manage local data) and improves compatibility with TypeScript and modern JavaScript tooling.

Breaking

• @required runtime feature flag is removed. (Previously an internal implementation detail)
• Typegen config Phase4 is renamed to Compat and is now the default. (Configuration setting for code generation)

New

• Typesafe Updaters: An experimental feature for a more ergonomic and type-safe approach to writing updaters for local data management.
• Improved TypeScript integration with support for client schema extension fields in Typesafe Updaters.

Fixes Worth Knowing

• Correctly handles GraphQL cursor connections. (Data loading mechanism)
• Fixes issues with file watching in TypeScript projects. (Automatic code reloading during development)
• Resolves bugs related to default arguments on required fields. (GraphQL query definitions)
• Incremental compilation now works correctly with undefined operation variables. (Faster build times)

TL;DR

Relay v12 introduces breaking changes to how type refinement and query cancellation work, alongside performance improvements like batched store updates and optimizations to fragment resolution.

Breaking

• Relay Runtime: Type refinement is now enabled by default. (Previously controlled by a flag)
• useQueryLoader & useLazyLoadQuery: Network requests are no longer automatically cancelled, except for live queries. (Affects data fetching behavior)

New

• Relay Network Logger: Now logs Suspense events for improved debugging. (Helps understand data loading states)
• Relay Compiler Playground: A first draft is available for experimenting with Relay compilation. (Web-based tool for Relay code)

Fixes Worth Knowing

• React: Resolved tearing issues in containers during rendering and commit. (Improves UI stability)
• Runtime: Fixed memory leaks in containers and FragmentResource. (Enhances performance and reduces resource usage)
• Subscriptions: Improved type safety for the useSubscription API. (Reduces errors when working with subscriptions)

Before You Upgrade

• Review your code for any reliance on the previous cancellation behavior of useQueryLoader and useLazyLoadQuery.
• Be aware that type refinement is now always enabled and adjust your code accordingly if you previously disabled it.

TL;DR

Relay now uses OperationExecutor instead of QueryExecutor, improving consistency and removing deprecated code, alongside numerous documentation updates.

Breaking

• QueryExecutor is now OperationExecutor (core data fetching class).
• RelayProfiler functionality has been removed (performance measurement tool).

Fixes Worth Knowing

• Fixed an issue where onNext callbacks in requestSubscription weren’t always called.

Before You Upgrade

Update your code to use OperationExecutor instead of QueryExecutor wherever applicable.

TL;DR

fetchQuery now returns an observable with request de-duping, offering improved performance and cache control, but requires code changes to adopt.

Breaking

• fetchQuery: Now returns an observable instead of a Promise, with new behavior for caching and de-duplication. Use fetchQuery_DEPRECATED to access the old functionality.
• getDataID: Renamed from UNSTABLE_DO_NOT_USE_getDataID and is now a stable configuration option.
• gcReleaseBufferSize: Default value increased to 10, improving cache reuse for certain fetch policies.
• UNSTABLE_renderPolicy: Defaults to “partial” – will be removed in the next stable release.

New

• Relay Hooks: New APIs are available in react-relay and react-relay/hooks, replacing the deprecated relay-experimental package.
• ConnectionHandler.getConnectionID: Added to simplify access to connection IDs for updaters and mutations.

Fixes Worth Knowing

• loadQuery now correctly retains queries in the environment when data is found in the store.
• ConnectionHandler now prevents creation of edges with undefined cursors.

Before You Upgrade

• Import fetchQuery_DEPRECATED from react-relay or relay-runtime if you need the previous fetchQuery behavior.

TL;DR

Relay now supports multiple edges when using @appendEdge and @prependEdge, improving flexibility when working with lists and connections.

Fixes Worth Knowing

• Error messages now display code context for easier debugging.
• Network requests are no longer accidentally canceled when using loadQuery (data loading function).
• loadQuery now deduplicates requests more effectively, reducing unnecessary network traffic.

TL;DR

Relay now supports configurable query cache expiration times (queryCacheExpirationTime) allowing you to control how long data is considered fresh, improving performance and data consistency.

Breaking

• Removed support for existingFragmentNames compatibility feature.

New

• Added queryCacheExpirationTime option to the Relay store, allowing control over data staleness.
• Introduced useSubscription hook (experimental) for simplified subscription usage.
• Added fetchPolicy support to fetchQuery (experimental) for more control over data fetching.

Fixes Worth Knowing

• Improved handling of persisted queries and fragment argument transforms.
• Fixed issues with 3D selections and alias generation.
• Resolved a data race in concurrent mode when loading more data.
• Corrected validation errors for connection handlers.

Before You Upgrade

• If you are using the existingFragmentNames compatibility feature, remove it from your code.

TL;DR

Relay v8 introduces a significant schema change requiring GraphQL Schema Definition Language (SDL) instead of the graphql-js schema, impacting custom implementations and potentially breaking existing setups.

Breaking

• Schema Format: Relay Compiler now requires SDL schema files, breaking compatibility with custom implementations relying on the graphql-js schema (e.g., custom enums, scalars).
• Mutation IDs: Mutations now use unique root IDs, breaking code accessing mutation data via store.getRoot().
• RelayStore.retain(): The signature changed; now accepts an OperationDescriptor created with createOperationDescriptor.
• Babel Plugin: No longer generates thunks, potentially affecting existing code.

New

• Data Invalidation: New primitives allow marking data as stale, triggering refetches for queries referencing it.
• useMutation Hook: A new hook simplifies mutation handling.
• Variables in Complex Types: Relay Compiler now supports variables within complex objects and arrays.

Fixes Worth Knowing

• Mutation IDs: Mutations now correctly create new root IDs, eliminating the need for clientMutationId.
• Optimistic Payloads: validateMutation now correctly handles lists of scalar fields in optimistic updates.
• Fragment Memory Leaks: RelayModernFragmentSpecResolver reduces memory leaks in React concurrent mode.

TL;DR

Relay now supports customizing how query parameters are written during compilation, offering greater control over request construction (compiler configuration).

New

• Customizable Query Parameters: The compiler now accepts a function to control how query parameters are written, enabling advanced request customization.
• Raw Query Preloading: preloadQuery() (experimental) can now accept a raw query string, simplifying usage without needing a dedicated parameters file.

Fixes Worth Knowing

• Required Fields with Defaults: The compiler now correctly validates required fields that also have default values.
• Non-Nullable Viewer Fields: The ViewerQueryGenerator now supports non-nullable Viewer fields.

Before You Upgrade

If you rely on internal Relay runtime exports in relay-experimental, ensure your code remains compatible after this update.

TL;DR

Relay v6 introduces significant internal changes to the Store interface and optimistic updates, alongside new features like a LocalQueryRenderer and data masking with the @inline directive, improving data handling and query performance.

Breaking

• The Environment no longer supports a configurable PublishQueue. (Internal change preparing for new connection representation.)
• The Store interface was updated with snapshot() and restore() methods. (Primarily impacts custom Store implementations.)
• ReactRelayQueryRenderer’s dataFrom prop is now fetchPolicy, with value changes (e.g., STORE_THEN_NETWORK to store-and-network).
• Minimum React version is now 16.9.0.
• environment.unstable_internal has been removed.

New

• LocalQueryRenderer: Renders data exclusively from the Relay store, offering a faster and more efficient way to display cached data.
• @inline directive & readInlineData(): Enables data masking (security feature) for functions instead of React components.
• @raw_response_type directive: Adds flow types representing the exact shape of the server response.

Fixes Worth Knowing

• Mock data generation is more robust, correctly handling null values, plural fields, and enums.
• Fixed an edge case in ConnectionHandler when a field is unset.
• Resolved a babel polyfill issue in the compiler.
• Persisted queries now work correctly with the --watch flag.

Before You Upgrade

• Update your React version to 16.9.0 or higher.
• Update dataFrom prop in ReactRelayQueryRenderer to fetchPolicy with the corresponding value change.

TL;DR

Relay v5 introduces a breaking change to how variables are passed to react-relay containers, now requiring fragment refs instead of React context.

Breaking

• Variable Passing: react-relay containers now require variables to be passed via fragment refs, not React context. (Context-based variable setting will no longer work.)

New

• Scalar Configuration: You can now pass custom scalar configurations to the compiler. (Allows for more control over data types.)
• Relay Config Package: A new relay-config package is available for managing compiler configurations. (Simplifies compiler setup.)

Fixes Worth Knowing

• Data Deduplication: Connection edges are now deduplicated based on DataID, improving data consistency. (Prevents duplicate data in lists.)
• Viewer Mutations: Fixed a bug where mutations on the viewer field would overwrite existing data. (Ensures data integrity during viewer updates.)
• Inline Fragment Types: Fixed a bug in flow type generation for inline fragments with duplicate field names. (Improves type safety.)

Before You Upgrade

• Update your components to pass variables through fragment refs instead of relying on React context.
• Review your compiler configuration and consider using the new relay-config package.

TL;DR

Relay v4 introduces breaking changes to fragment and container definitions, requiring an explicit object wrapper for graphql tags.

Breaking

• Fragment, Refetch, and Pagination Containers now require an object as the fragment declaration (GraphQL tag must wrap an object). Use the provided codemod to update.
• ConnectionTransform now generates additional selections under existing edges and pageInfo fields, potentially affecting aliased fields.
• Compiler enforces directive location validation against the schema.
• Compiler requires all @arguments to be defined on the callee.

New

• Full support for client schema extensions allows defining complete GraphQL types on the client.
• QueryRenderer now de-duplicates identical requests for improved performance.

Fixes Worth Knowing

• Compiler no longer errors when the watchman CLI is missing.

Before You Upgrade

• Run the provided codemod to update fragment and container definitions to the new object wrapper requirement.

TL;DR

Relay has been significantly updated, removing the older "Classic" version and streamlining the package structure for modern GraphQL (graph data query language) development.

Breaking

• Relay Classic and Compat have been removed.
• The react-relay/modern import path has changed to react-relay/.

New

• Experimental support for @stream and @defer directives has been added in the QueryExecutor, enabling more efficient data fetching.
• @module can now be used outside of @match, allowing for new data dependency patterns.

Fixes Worth Knowing

• Enum values in schemas now print correctly as enum names instead of internal values.
• commitMutation() now consistently calls onCompleted with null errors when no errors occur.
• Optimistic mutation payloads now work correctly in sequential operations.

Before You Upgrade

Update your import statements to use react-relay/ instead of react-relay/modern/. Remove any dependencies on Relay Classic or Compat.

TL;DR

Relay v2.0 introduces significant internal changes, most notably migrating to the new React Context API, requiring updates to any code directly using the legacy context.

Breaking

• Relay now uses the new React Context API (application programming interface) instead of the Legacy Context API.
• The @deferrable directive is no longer supported.
• relay-compiler’s inputFieldWhitelist is renamed to optionalInputFields.
• The return type of environment.unstable_internal.getSelector(...) has changed.

New

• Fragment Ownership: Fragments can now link to their owning query, improving flexibility and enabling future API changes.
• Persisted Queries: A mechanism for using persisted queries is now available.

Fixes Worth Knowing

• Fixed issues with out-of-order payloads in QueryRenderer.
• Corrected double-fetching behavior when using React Concurrent mode.

Before You Upgrade

Update your graphql package to version 14.0.0 and react to 16.5.0 to ensure compatibility. Review any code directly accessing Relay context to migrate from the Legacy Context API to the new React Context API.

TL;DR

Relay now combines the graphql-compiler and relay-compiler into a single relay-compiler and introduces fragment ownership, improving performance and enabling future API flexibility.

Breaking

• The graphql-compiler has been merged into relay-compiler.
• The return type of environment.unstable_internal.getSelector(...) has changed.

New

• Fragment Ownership: Fragments can now link to their owning query, removing React Context dependency.
• Persisted Queries: Supports using pre-prepared queries on the server (improves performance).
• @arguments directive now accepts literal values.

Fixes Worth Knowing

• Fixed an issue with out-of-order payloads in QueryRenderer.
• Resolved a problem with PaginationContainer updating with new props.

Before You Upgrade

Update your build process to use the unified relay-compiler instead of both graphql-compiler and relay-compiler.

TL;DR

Relay now supports TypeScript and Create React App without requiring project ejection, thanks to new language plugins and a macro-based Babel plugin.

New

• TypeScript Support: Extend Relay with plugins (third-party extensions).
• Create React App Integration: Use Relay in Create React App projects without ejecting.

Fixes Worth Knowing

• Fixed double-fetching issues when using React Concurrent mode.
• Resolved rendering problems with multiple QueryRenderer components using the same query.

Before You Upgrade

• Ensure all Relay packages are kept at the same version to avoid issues with the removed relay-compiler peer dependency.
• Remove any usage of the deprecated RelayNetwork.streamQuery and RelayNetwork.sendSubscription methods.

TL;DR

Relay now supports TypeScript and works with Create React App (a popular React project setup) without requiring you to "eject" from the default configuration.

Breaking

• RelayNetwork.streamQuery and RelayNetwork.sendSubscription have been removed. (Deprecated methods for data fetching)

New

• TypeScript support is now possible via language plugins. (Extends Relay to other languages)
• Relay works with Create React App without ejecting. (Simplifies project setup)

Fixes Worth Knowing

• Fixed an issue causing double fetches in React Async development mode. (Improves performance during development)
• Removed an unnecessary peer dependency. (Simplifies package management)

Before You Upgrade

Ensure all Relay packages are kept at the same version to avoid compatibility issues.

TL;DR

This release updates Relay to support the latest GraphQL specification and introduces a rollback method for mutations, improving error handling and data consistency.

New

• RelayGraphQLMutation is now part of the public API, enabling more flexible mutation handling.
• A rollback method was added to RelayGraphQLMutation to allow for cleaner error recovery after a mutation fails.

Fixes Worth Knowing

• Custom scalar field arguments now print correctly in GraphQL queries.
• Fixed an issue preventing the use of "node" as a key in mutation responses.

Before You Upgrade

Update your babel-relay-plugin to use [email protected] to take full advantage of the GraphQL specification support.