Version 19.0.0 Release Notes

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:
  • Quick Start - A single page guide to get Relay up and running locally
  • Production Setup - A list of best practices for setting your Relay application up for production use cases
  • Relay Babel Plugin - Information about Relay's Babel plugin and how to install it in your app.
  • Relay Environment - API docs for the core Relay environment
  • Runtime Configuration - Documentation covering runtime feature flags and more
• 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 no longer 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 unstable 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 required 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 unnecessary 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 compatibility 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)