github facebook/relay v18.0.0
Version 18.0.0 Release Notes
on GitHub

latest release: v18.1.0
one month ago

With version 18, the Relay team at Meta and our community of contributors have made several significant improvements to Relay:

  • Improved validation of argument types
  • @alias released as stable
  • @catch to detect and granularly handle field errors
  • @throwOnFieldError and @semanticNonNull to avoid having to handle the nullability of fields which are only null in the case of error.
  • Intellisense for your Relay config file
  • Rename refactoring tools and inlay hints for fragment arguments

Read all about them in more detail below:

Breaking Changes

Improved validation of field and fragment arguments

Previously we were not correctly type-checking arguments passed to client-defined fields, such as Relay Resolvers and Client Schema Extensions. This new release adds that validation. If you need to opt out of this validation for any reason, you can enable the disable_full_argument_type_validation compiler feature flag. 

{
    // ... rest of config
    "featureFlags": {
        "disable_full_argument_type_validation": {
          "kind": "enabled"
        }
     }
}

Major features

@alias fragment aliases released as stable

Aliased fragments are a Relay feature that lets you access fragments spreads and inline fragments as named properties. This can be especially helpful for fragments which might be conditionally fetched due to @skip/@include or type conditions which might not match. With @alias these fragments get typed as nullable properties allowing you to check at runtime if they've matched or not before trying to use the data.

Read more about @alias

@catch

@catch, enabled by default will let you check at runtime if a field errored. This can allow you to disambiguate between true nulls returned by your server, and fields which are null due to field level errors.

Read more about @catch

@throwOnFieldError

@throwOnFieldError can be added to fragments and queries and will cause any field errors within that fragment/query to throw when read. This ensures that all null values you encounter are true nulls as returned by your field resolvers on the server, and not field level errors that have been coerced to null.

Read more about @throwOnFieldError

Semantic Nullability

@throwOnFieldError unlocks a powerful new feature when combined with a schema that has fields annotated with @semanticNonNull. @semanticNonNull can be added to fields which have been made nullable in the schema only to enable more robust error handling, but are not expected to return null expect in the case of errors.

Within fragments or queries annotated with @throwOnFieldError, fields annotated with @semanticNonNull will be typed as non-nullable. This has the potential to dramatically reduce the number of null checks you need to perform inside your product code, while also making your product code more "correct" by treating all field errors as explicit errors.

Read more about Semantic Nullability

Relay Resolvers can now have access to context

Thanks for Mark Polak and Drew Atkinson from Microsoft, Relay Resolvers can now be configured to accept a shared context object, similar to standard GraphQL resolvers.

Pull Request

Read more about Resolver context

Ability to opt out of Relay Compiler source control integration

Thanks also to for Mark Polak from Microsoft, the Relay compiler config now supports the option "noSourceControl": true which will ask the Relay compiler to not automatically try to add/remove files from Git or Mercurial.

Pull Request

Editor Integration Improvements

Thanks to Tobias Tengler, Relay's editor support now includes:

  • Intellisense (autocomplete, hover tooltips, diagnostics) for the Relay config file. This fills a critical gap since the Relay config is quite under-documented. (#4724) by tobias-tengler
    • Editor integration (#4724) by tobias-tengler
    • Generate JSON schema for compiler config (#4723) by Jordan Eldredge
  • Rename refactoring tools (#4581) by tobias-tengler
  • Add Inlay Hints for Fragment arguments (#4740) by tobias-tengler
  • Improved documentation links in errors and hover tooltips (#4741) by tobias-tengler

Additional runtime logging integrations

  • [9b24ad]: Log notify stats by Tianyu Yao
  • [ed8a7f]: Add logging for DataChecker by Tianyu Yao
  • [462b01]: Add logging for store lookup by Tianyu Yao
  • [1faea5]: Add more loggings for GC by Tianyu Yao
  • [f42215]: Add more information to execute.next log by Tianyu Yao

Additional Improvements

  • [e84b10]: Inline enum values in hot code paths by Jan Kassens
  • [ebd987]: Strictify relay entrypoint typing by Sam Zhou
  • [989ebf]: Improve error reporting for argument type errors by Jordan Eldredge
  • [3ba54c]: Use more precise variance for some relay types by Sam Zhou
  • [9f0e9e]: Improve schema-validation error messaging by Steven Chaitoff
  • [eec960]: Report schema parsing errors for synced schema sources (#4719) by tobias-tengler
  • [176f96]: Parallelize dumping schemas to disk by Deepak Singh
  • [e492d7]: Fix out of date component name in Mutations & Updates by Lynn Yu
  • [0f49c2]: Skip importing export types in TS (#4754) by Drew Atkinson
  • [aba9e9]: Ignore null/undefined queries in entrypoints by Jordan Eldredge
  • [d5f1a0]: Correctly report unaliased fragments within inline fragment with @Skip by Jordan Eldredge
  • [2ad28f]: Disallow Node refetchable query on interfaces without implementations by Tianyu Yao
  • [c446d4]: Fix Relay incremental build for enums by Evan Yeung
  • [7998bc]: Support multiple @module fragments in the same selection if they have @alias (#4744) by Jordan Eldredge
  • [df2aca]: I think we could allow @module in the same selection if they have different keys by Jordan Eldredge
  • [294cb8]: Ensure we strip alias metadata from selections within inline fragments by Jordan Eldredge
  • [531c6f]: Fix syntax error when using the new relay resolver by Tianyu Yao
  • [6e47ac]: Return and handle all required_on_non_null_field errors by Gordy French
  • [2b5028]: Ensure documents are synced before calculating completions #4473 by Jordan Eldredge
  • [c43429]: Add editor support for JSON config schema (#4724) by tobias-tengler
  • [4d2fe9]: Error on multiple graphql type definitions on one flow type by Tianyu Yao
  • [99003d]: Prevent using @alias within @match by Jordan Eldredge
  • [7491d3]: Update relay resolve API doc by Tianyu Yao
  • [5d1225]: Fix incremental build when enum field argument changes by Monica Tang
  • [0c5d69]: Support incremental schema change for union changes by Lynn Yu
  • [d53615]: Refactor alias to always use inline fragments (and compose with other features) by Jordan Eldredge
  • [86800e]: Add compiler command to emit json schema of config file by Jordan Eldredge
  • [80e041]: Minor spell checking by Gordy French
  • [6a2c39]: Validate that @match fields always have supported arg by Jordan Eldredge
  • [7bd521]: Only validate alias within each selection set by Jordan Eldredge
  • [44cbff]: Support Client Edge to Client Union for strong types by Monica Tang
  • [d35688]: Avoid reading inline fragments if abstract type condition does not match by Jordan Eldredge
  • [3787b8]: Handle case where @required bubbles to @Aliased inline fragment on abstract type by Jordan Eldredge
  • [349334]: @required should bubble nullable to parent semantic-non-null linked field by Gordy French
  • [f96121]: Allow abstract inline fragments to be omitted by Daniel Lo Nigro
  • [43bd9b]: Revert D54206758: Validate edgeTypeName argument points to an existing type by Amy Hwang

Documentation Improvements

  • [c54830]: Docs for @catch by Itamar Kestenbaum
  • [f07f56]: Update semantic nullability docs to remove feature flag that is no-longer needed by Jordan Eldredge
  • [861caa]: Fill in definitions for @stream and @stream_connection in Glossary by Lynn Yu
  • [e46ba9]: Document current support for experimental semantic nullability (#4770) by Jordan Eldredge
  • [642e03]: Add definitions for @LiVe and @live_query to glossary by Lynn Yu
  • [27b2a1]: Document resolvers constants by Jordan Eldredge
  • [175098]: @throwOnFieldError documentation by Gordy French
  • [794cc3]: Pagination documentation fixes by Lynn Yu
  • [23a7c2]: Fix the connection key in the mutations tutorial (#4751) by Sviatoslav Abakumov
  • [bf6153]: Fix small errors in docs by Lynn Yu
  • [99f4f6]: Organize sidebar for oss site by Evan Yeung
  • [0ab687]: Re-organize hierarchy of docs interally by Evan Yeung
  • [aa6538]: UseQueryLoader clarification by Monica Tang
  • [9f314a]: Fix GraphQL Field name for story thumbnail examples by Jerry Francois
  • [285dc2]: Spelling and capitalization by Gordy French
  • [0e57c3]: Fix unclosed jsx tag by Monica Tang
  • [7fccac]: Fix minor typo in editor-support.md (#4721) by SY Ryu
  • [c632b4]: Link to Relay website @defer @stream docs by Monica Tang
  • [d61ce0]: S/class/className/ in MDX (#4716) by Paul O’Shannessy
  • [98d76c]: Add instructions to run relay compiler after query update (#4718) by Matthew Pawley
  • [dbae5c]: Link GQL node definition in useRefetchableFragment section by Danny Zou

Miscellaneous

  • [457e0c]: Update relay compiler README by Monica Tang
  • [36e9ea]: Remove loadQuery during render warning (#4731) by Jordan Eldredge

Experimental Changes

  • [8cb637]: Support in useFragmentInternal by Joe Savona
  • [9125e2]: Support returning an interface in IdOf by Tianyu Yao
  • [a1ce49]: Schemagen should allow list items to be true non-null by Gordy French
  • [a726fc]: Add semanticNonNull support to generated schemas by Gordy French
  • [4a378d]: Add support for global custom scalars by Evan Yeung
  • [d3afbb]: Support @deprecated annotation by Lynn Yu
  • [2efe7a]: Add support for fragment arguments by Evan Yeung
  • [ce4388]: Add test for conflicting arguments by Evan Yeung
  • [f239b7]: Add new relayresolver syntax to documents by Tianyu Yao
  • [b26951]: Disallow non-nullable return type by Tianyu Yao
  • [2152df]: Support attaching resolver fields onto Query by Tianyu Yao
  • [6ddd80]: Map Flow -> GraphQL Scalars in schema gen by Evan Yeung
  • [628b42]: Attach locations to parent types by Tianyu Yao
  • [884c96]: Resolve return flow types to their flow types by Tianyu Yao
  • [a1b186]: Unify processing weak fields by Tianyu Yao
  • [217eb3]: Unify processing rootFragment fields by Tianyu Yao
  • [5ee605]: Extract module for getting import and export by Tianyu Yao
  • [2a3c04]: Fix IdOf Flowtype by Tianyu Yao
  • [615020]: Add variable cycle detection by Jordan Eldredge
  • [bb6f7b]: Add correct root fragment information by Evan Yeung

And more

There were over 100 additional commits since our last release which have been omitted from this doc

Check out latest releases or
releases around facebook/relay v18.0.0

Don't miss a new relay release

NewReleases is sending notifications on new releases.

Get notifications