facebook/relay v18.1.0 on GitHub

Following up from our v18.0.0 release last month, v18.1.0 provides a number of fixes and improvements, adds some new experimental APIs, and ships some long-running experimental features as stable.

Relay Resolvers are now stable

For the past several years we've been iterating on Relay Resolvers which provided a structured and typesafe way to model client state and derived data in your GraphQL graph. As of this release, Relay Resolvers are enabled by default and no-longer experimental. As part of this stabilization we shipped fixes for Relay Resolvers when used with TypeScript and fixed a few edge cases related to how errors encountered by resolvers are handled.

[d10786]: Update docs now that resolvers are stable by Jordan Eldredge
[4e5377]: Remove Relay Resolver compiler feature flag by Jordan Eldredge
[7b8f1f]: Remove ENABLE_RELAY_RESOLVERS runtime feature flag by Jordan Eldredge
[1467b6]: Stabilize LiveResolverStore as the new implementation of RelayModernStore (#4806) by Jordan Eldredge
[dec5ee]: Avoid running resolver code if root fragment throws with @required(action: THROW) (#4799) by Jordan Eldredge
[478274]: Ensure we import the type of a resolver for RelayResolverValue fields by Jordan Eldredge
[852fbc]: Improve edge resolver error messages by Gordy French
[575f20]: Add satisfies type assertion for typescript (#4797) by Drew Atkinson
[2314f4]: Document relay field logger (#4809) by Jordan Eldredge

Improvements to error @catch

We released @catch in v18.0.0 and are very excited about the capabilities it enables. Check out Itamar Kestenbaum's GraphQL conf talk about it here: Build Confidently: How @Catch and Error Handling Pave Way in Field Nullability.

Since that release we've made a few improvements:

Fields within a @catch directive that are marked as @semanticNonNull in the schema now generate non-nullable TypeScript/Flow types. See semantic nullability.
Errors exposed to product code by @catch no-longer include the error message. This is because GraphQL error messages are generally not safe to show to users. These error messages can still be accessed by the field logger provided to your Relay Environment. In the future we plan to let users opt into allowing safe error messages through to product code.

[26b78d]: Take advantage of @semanticNonNull within @catch (#4794) by Jordan Eldredge
[6a038d]: Replace actual server-side error with generic "server error" message by Itamar Kestenbaum
[6c8827]: Don't report missing fields within an unmatched inline fragment by Jordan Eldredge
[2314f4]: Document relay field logger (#4809) by Jordan Eldredge

Compiler Error Reporting

We've improved how errors are reported by the Relay compiler to ensure we report as many errors as possible, and each error includes sufficient context.

[9edbb0]: Report validation errors for all segements of a proejct by Jordan Eldredge
[adaf8a]: Report location of operation that does not define variable by Jordan Eldredge

New "Copy Operation" VSCode command

Our VSCode extension now includes a command to quickly copy the full text of a query directly from within your editor.

[8d2380]: Add copy operation command (#4778) by Tobias Tengler

Experimental APIs for reading fragment data outside of React

In some cases it can be useful to read a fragment outside of a React hook. However, doing this requires handling a number of concerns.

The fragment data may not yet be ready (@defer or Relay Resolver suspense).
The fragment may error (@throwOnFieldError, @required(action: THROW))
The fragment's data might change over time.

To enable users to read fragment data while correctly handling these cases, we've added two experimental APIs:

observeFragment: Read a fragment as a stream of states where each state might be loading, error, or value.
waitForFragmentData: Read a fragment as a promise which will resolve when data is available, or reject if an error is encountered.

[6f0cbe]: Upstream observeFragment and waitForFragmentData to relay-runtime by Jordan Eldredge
[36eecf]: Documentation for observeFragment and waitForFragmentData by Jordan Eldredge

Docs

Thanks to members of our community for submitting pull requests to improve our docs:

[e133fe]: Remove reference to the Google Chrome Extension Store from the installation guide for Relay Developer Tools by Jakub KopÃ…â„¢iva
[e41490]: Replace story.image for story.thumbnail (#4793) by Theo Kouzelis
[e95a5a]: Update mutations-updates.md in Tutorials (#4765) by Jbee
[0cf094]: Update error handling and semantic nullability docs to include talks and links (#4800) by Jordan Eldredge

Improvements

[08c74e]: Validate semantic-non-null interface implementations by Gordy French
[a5b963]: Renaming missing_field log event types to missing_required_field by Itamar Kestenbaum
[186c91]: Call cleanup of insertion effects when hidden (#30954) by rickhanlonii (Meta Employee)
[ba0b46]: Add logging for normalization by Tianyu Yao
[792628]: Relay: Allow omitting exists on ExternalFileSourceResult by Nico Reed
[f1ee92]: Check pruned fields blocklist for undefined fields by Steven Chaitoff
[23958c]: Make metadata_for_machine keys string constants by Steven Chaitoff
[8d0302]: Relay: Remove unused code from oss code by Nico Reed
[6d36d7]: Fix mockClientData with generateDeferredPayload = true by Fernando Gorodscy

Experimental

We are always continuing to evolve and improve Relay. These changes are part of features or implementations which are either in progress or are being experimented with internally.

[cb1b4d]: Add feature flag and config option to give custom path for artifacts by Monica Tang
[4acf3f]: Make usePaginationFragment compatible with by Joe Savona
[f9365f]: Attempt to avoid cycled when expanding updated ids to include impacted resolvers (#4792) by Jordan Eldredge
[59b2a6]: UseQueryLoader() (and refetch()) compatibility with by Joe Savona
[2f997b]: Update generated data driven dependency metadata for client 3D by Lynn Yu
[790d46]: Update Relay API for disk caching by Evan Yeung
[bb30bb]: Add feature flag for reader AST module imports by Evan Yeung
[f0761b]: Add a priority flag to task scheduler for store network updates by Tianyu Yao
[6f8f79]: Move corpus creation of program into helper function by Gordy French

facebook/relay v18.1.0 Version 18.1.0 Release Notes on GitHub