Skip to main content

Relay v19.0

· 9 min read

Relay 19.0.0 includes many documentation improvements, bug fixes, and improved capabilities.

@alias required on conditional fragments​

To improve type safety, the @alias directive is now required on all fragments that are only conditionally fetched either due to @skip/@include or fragment type conditions which only conditionally match. You can opt out of this validation on a per-fragment basis with the @dangerously_unaliased_fixme directive.

To enable incremental migration we include a codemod which will automatically add the @dangerously_unaliased_fixme in all required places:

npx relay-compiler codemod mark-dangerous-conditional-fragment-spreads

You can also opt out of this validation entirely via compiler config feature flag:

{
  // ...
  "featureFlags": {
    "enforce_fragment_alias_where_ambiguous": {
      "kind": "disabled"
    }
  }
}

Improved Docs​

We've merged ~30 commits to clean up and improve our docs since the last release:

  • Added new pages:
  • Removed outdated or orphaned doc pages
  • Streamlined and fixed issues in existing docs

React 19 Compatible​

React 19 is now a valid peer dependency of Relay (#4944) by Krzysztof Karol (commit)

Breaking Changes​

  • Relay now defaults to generating ES module imports in its generated js files. You can add "eagerEsModules": false in your relay.config.json to opt back into the old behavior. (commit)
  • Relay's NPM modules nolonger include a pre-bundled module. (#4935) by Iha Shin (commit)

Improvements​

  • Avoid duplication in config JSON Schema by Jordan Eldredge (commit)
  • Go to definition in the LSP can now navigate to the correct column (#4969) by Jordan Eldredge (commit)
  • Make store an optional argument when constructing a Relay Environment by Jordan Eldredge (commit)
  • Include mixed loggerContext in handled snapshot errors by Itamar Kestenbaum (commit)
  • Add id collision logging in RelayResponseNormalizer with typename metadata by Monica Tang (commit)
  • Mark useLazyLoadQuery options as ReadOnly by Marco Wang (commit)
  • Add onPause in cacheConfig for Relay subscriptions by Aria Fallah (commit)
  • Add typename metadata to id collision log event by Monica Tang (commit)
  • Allow @dangerously_unaliased_fixme on updatable fragment spreads by Jordan Eldredge (commit)
  • Add a feature flag to throw on nested updates in dev by Tianyu Yao (commit)
  • Do not emit union type for __typename selection on non-abstract type (#4923) by tobias-tengler (commit)
  • Reenable warning if fetchQuery is called in render (using new unsatable React APIs) by Jordan Eldredge (commit)
  • Log ID collisions in production by Monica Tang (commit)
  • Add log events by Monica Tang (commit)
  • Pass operation availability to the network layer for loadQuery by Tianyu Yao (commit)
  • Add compiler validation to error on resolver that returns plural server type by Jordan Eldredge (commit)
  • Enable by default recreating loadMore optimization by Andrei Marchenko (commit)
  • Allow @dangerously_unaliased_fixme in updatable fragments by Jordan Eldredge (commit)
  • Error on empty selections after fragment argument transform (#4908) by tobias-tengler (commit)
  • Add error message to Resolver error by Itamar Kestenbaum (commit)
  • Fix codemod crashing on aliases in inline fragments by Gordy French (commit)
  • Allow required alias codemod to be applied to a rollout range by Jordan Eldredge (commit)
  • Add onResume in cacheConfig for Relay subscriptions by Xiangxin Sun (commit)
  • Shorten relay read time resolver key prefix by Tianyu Yao (commit)
  • Arguments in prefetch pagination variables bug fix by Lynn Yu (commit)
  • handle local variables vs global variables in prefetch pagination by Lynn Yu (commit)
  • Manual rebase of: Enable __token field based on compiler schema config #4347 (#4889) by Jordan Eldredge (commit)
  • Fix conditional sub-selections in raw response type (#4774) by tobias-tengler (commit)
  • Add execute.unsubsribe logging by Tianyu Yao (commit)
  • Enhance schemaExtensions to Support Both Files and Directories (#4859) by Sverre Johansen (commit)
  • Add plural fragment support to observeFragment() (#4862) by Iha Shin (commit)
  • Handle CRLF when parsing docblocks (#4865) by Sverre Johansen (commit)
  • Validate that client schema extensions within @throwOnFieldError have @catch by Jordan Eldredge (commit)
  • Add @catch to client schema extension fields within @throwOnFieldError by Jordan Eldredge (commit)
  • Make Result type fields readonly by Jordan Eldredge (commit)
  • Limit WalkDir to the root directories referenced by the configuration (#4850) by Sverre Johansen (commit)
  • Simplify dependencies for loadMore function by Andrei Marchenko (commit)
  • Propegate empty arrays into the store when handling errors on noncompliant lists by Ryan Holdren (commit)

Bug fixes​

  • Fix nullable refetchedFragmentRef in checkSameIDAfterRefetch (#4945) by Krzysztof Karol (commit)
  • Add missing readFragment export in relay-runtime (#4931) by Jay Jaeho Lee (commit)
  • Fix bug with caching incomplete used variables for fragment cycles by Jordan Eldredge (commit)
  • Fix observeFragment triggering unhandled rejections on network error (#4885) by Iha Shin (commit)
  • Checked for missed updates in effect create phase by Jack Pope (commit)
  • Avoid writing to stdout in LSP by Jordan Eldredge (commit)
  • Run requried transform on IR before validating @required on semantic non null fields in LSP by Jordan Eldredge (commit)
  • Fix: Don't report @required on field that can be null due to @required bubbling as unnessesary by Jordan Eldredge (commit)
  • Unbreak LiveState unsub when references.size === 0 (#4832) by Tom Aylott (commit)
  • Remove PointerAddress from generate_typename by Gordy French (commit)
  • Context not properly provided through data injector and subscriptions (#4846) by Mark Polak (commit)
  • Fix rare client_extension instability by Gordy French (commit)
  • Enforce TTL-based GC when release buffer is full by Monica Tang (commit)
  • Fix usePagination stuck in isLoading by Tianyu Yao (commit)

Documentation Improvements​

  • Update language to reference hooks not containers (#4964) by Jordan Eldredge (commit)
  • Move the "Organizing Operations" tutorial page into the guides by Evan Yeung (commit)
  • Fix code examples in the connections tutorial page by Evan Yeung (commit)
  • Migrate most blockquotes in our docs to admonitions by Evan Yeung (commit)
  • Update VSCode docs/errors to use pathToRelay (#4965) by Jordan Eldredge (commit)
  • Iteration on new quick start guide based on feedback (#4966) by Jordan Eldredge (commit)
  • Quick Start: Add note about watchman by Jordan Eldredge (commit)
  • Remove "TBD" sections from the docs by Evan Yeung (commit)
  • Rework onboarding flow by Jordan Eldredge (commit)
  • Remove migration and compatability pages by Jordan Eldredge (commit)
  • Make footer logo smaller by Monica Tang (commit)
  • Delete some pages by Monica Tang (commit)
  • Remove orphaned page "workflow" by Jordan Eldredge (commit)
  • Delete empty docs pages by Monica Tang (commit)
  • Fix typos and improve clarity in the tutorial by Evan Yeung (commit)
  • Delete legacy API docs (with broken links) by Monica Tang (commit)
  • Fix subscription call signature in observeFragment docs by Jordan Eldredge (commit)
  • Fix broken markdown in OssOnly blocks by Itamar Kestenbaum (commit)
  • Fix broken markdown in FbInternalOnly blocks by Itamar Kestenbaum (commit)
  • Document configuring relay runtime globally (#4906) by Jordan Eldredge (commit)
  • Update docs on usePaginationFragement & transitions in Relay tutorial. (#4842) by Daniel Stocks (commit)
  • fix mistake in refetching-queries-with-different-data by Lynn Yu (commit)
  • Add documentation for RecordSourceProxy by Lynn Yu (commit)
  • Remove dead links from Relay users page by Evan Yeung (commit)
  • Add documentation for Relay performance logger by Tianyu Yao (commit)
  • Add docs for @gqlField resolvers by Evan Yeung (commit)
  • Document resolvers returning abstract types by Jordan Eldredge (commit)
  • Start to fix Updating Data section of relay docs by Lynn Yu (commit)
  • make it clear that 3D @module will only work if each fragment is on a different concrete type by Lynn Yu (commit)
  • Fix typo in documentation by Allan Spreys (commit)

Experimental Changes​

  • Fix relay reader module import bug by Lynn Yu (commit)
  • Load component module earlier into record store 1/2 by Lynn Yu (commit)
  • Generate data driven dependencies for static resources used by exec resolver normalization artifacts by Lynn Yu (commit)
  • add ability to configure operationModuleProvider path separately from componentModuleProvider by Lynn Yu (commit)
  • Check for .read_time_resolvers in module_metadata before adding exec time directive in split_module_import by Lynn Yu (commit)
  • add exec time resolvers directive to split module import by Lynn Yu (commit)
  • Generate exec time ASTs in rootFragment $normalization files by Tianyu Yao (commit)
  • Compiler client 3D changes to support exec time resolvers by Lynn Yu (commit)
  • Create feature flag for typename prefixing of ids by Monica Tang (commit)
  • support client 3d on concrete objects by Lynn Yu (commit)
  • Add test cases for @defer behavior in read time resolvers by Tianyu Yao (commit)
  • Modify _readClientSideDirectiveField in RelayReader to work for exec time resolvers by Lynn Yu (commit)
  • Allow @match on client edges by Tianyu Yao (commit)
  • Add enabledProvider argument inside @exec_time_resolvers directive (runtime + artifacts) by Lynn Yu (commit)
  • Modify useLazyLoadClientQuery to take a flag for exec time resolvers on or off by Lynn Yu (commit)
  • amend compiler changes to handle exec_time_resolvers ONLY case differently by Lynn Yu (commit)
  • COMPILER changes add enabled argument inside @exec_time_resolvers directive by Lynn Yu (commit)
  • Parse the @gqlField docblock for the description and deprecated tag by Evan Yeung (commit)
  • Add logic to find property lookup resolver docblocks by Evan Yeung (commit)
  • Pipe information through compiler for simplified resolver generation for property lookup resolvers by Evan Yeung (commit)