Upcoming Relay Releases

[jstejada]

Today we are publishing the release candidate for Relay v11, which will include a stable release of Relay Hooks. We wanted to share with the community what our plan is for upcoming releases surrounding Relay Hooks, and what you can expect.

Over multiple versions we’ll move some of the current APIs, mainly the higher order component (HOC) APIs out of the main react-relay export, but those APIs will continue to be available.

Relay v11-RC - The one with Relay Hooks (RC) - Feb 26

This version will allow you to use new React Hooks based APIs, either from the react-relay package together with the familiar create*Container APIs or, if you want, you can use hooks exclusively with the react-relay/hooks module.

Relay v11.0.0-rc.0 - Release candidate:

• Install: npm install react-relay@dev relay-runtime@dev
• This release will export the following new APIs from the main react-relay package, as well as from react-relay/hooks:
  • EntryPointContainer
  • RelayEnvironmentProvider
  • loadQuery
  • loadEntryPoint
  • useFragment
  • useLazyLoadQuery
  • useEntryPointLoader
  • useQueryLoader
  • useMutation
  • usePaginationFragment
  • usePreloadedQuery
  • useRefetchableFragment
  • useRelayEnvironment
  • useSubscribeToInvalidationState
  • useSubscription
  • fetchQuery (new version)
• This release will also begin exporting the following APIs from react-relay/legacy:
  • QueryRenderer
  • LocalQueryRenderer
  • MutationTypes
  • RangeOperations
  • ReactRelayContext
  • createFragmentContainer
  • createPaginationContainer
  • createRefetchContainer
  • fetchQuery_DEPRECATED (legacy version)
• Check out our release notes for a summary of changes (breaking and otherwise) included in this release.

Additional Planned Changes for v11:

• We will publish our updated docs and website with the next stable release. The new docs will be more comprehensive, and are still are ongoing updates. In the meantime, in order to access some documentation for the APIs in this RC, you can access our current our current experimental docs, or manually build the docs in website-v2.
• UNSTABLE_renderPolicy will be removed. The concept of a render policy will not need to be surfaced to external consumers of our APIs, and rendering should work as expected; the default behavior will always be “partial”. See the release notes for more details.

React Compatibility:

• Relay Hooks can be used with React 17, although React support and general guidance for usage of Suspense for Data Fetching is still not ready, and the React team is still defining what this guidance will be for upcoming releases.
• This means that there will be some limitations when using Relay Hooks with Suspense in React 17, which we will document in our release. Specifically, the current release includes a subset of features that work with both synchronous rendering and concurrent rendering. In order to fully support Suspense for Data Fetching, we also need features such as concurrently rendering suspended trees, and transitioning to new trees when data is refetched. The APIs we’re releasing today will allow us to support concurrent rendering with the same APIs in future versions of React.
• When a future version of React is released that fully supports concurrent rendering and Suspense for Data Fetching, Relay will also make a new major release alongside the React release. That release will likely include breaking changes that we will document for the upgrade.

We will share more external communications with the community once the stable release is published.

Relay v11 - The one with Relay Hooks (Stable) - March

This release shouldn’t include any significant changes from the release candidate, apart from the planned changes mentioned above, or any changes to issues encountered in the initial RC. We might release additional release candidates before the stable release.

Relay v11.0.0:

• This will be the next major stable version of Relay including Relay Hooks. We expect this release will include the same exports as Relay v11.0.0-rc.1
• We will share more external communications with the community as well as publish our updated docs once this stable release is published.

Relay vXX - Phasing out Relay Containers - Date TBD

In this release we will start phasing out containers and other legacy APIs by warning when they are imported from the main react-relay module. Migrating an existing app should just involve updating the imports of legacy APIs to react-relay/legacy where they will continue to be available.

Relay vXX - Separating Relay Containers - Date TBD

This release will be a major release that removes the legacy APIs from the main react-relay module. If all warnings from the previous release were fixed, this should not be a breaking change. The legacy APIs will remain exported from react-relay/legacy.

In order to consolidate our hooks exports, we will also start warning when new Relay Hooks APIs are imported from react-relay/hooks and not from the main react-relay package. To fix, you can update to import from react-relay. In a subsequent release, we will remove react-relay/hooks since it should be the same as react-relay.

Relay vXX - React Updates - Date TBD

When a future version of React is released that fully supports concurrent rendering and Suspense for Data Fetching, Relay will also make a new major release alongside the React release. This release will likely include breaking changes that we will document for the upgrade.

Please feel free to comment if you have any feedback or suggestions. Thank you!

[koichik]

Thanks for your great works!

• This release is compatible with React 17.

React v17 doesn't support Concurrent Mode yet and Relay Hooks uses "Suspense for Data Fetching".
However, React team said:

https://github.com/facebook/react/blob/master/CHANGELOG.md#16131-march-19-2020

Fix bug in legacy mode Suspense where effect clean-up functions are not fired. This only affects users who use Suspense for data fetching in legacy mode, which is not technically supported. (@acdlite in #18238)

Can we use Relay Hooks with React v17 (i.e. Legacy Mode) officially?

[jstejada]

Hey @koichik, thanks for bringing this up, and apologies we didn’t communicate this more clearly in the release plan.

Although Relay Hooks uses Suspense for some of its APIs, it is correct that support, general guidance, and requirements for usage of Suspense for Data Fetching are still not ready, and the React team is still defining what this guidance will be for upcoming releases.

With that said, even though there are still things to figure out before Suspense for Data Fetching can be broadly implemented and adopted, we want to move forward with the release of Relay Hooks even on React 17 for a few reasons:

Relay was a very early adopter of Suspense, and collaborated with React on the research of Suspense for Data Fetching. It was one of the first testing grounds for using Suspense in production, and helped inform some of its design decisions. As such there are still parts of our Suspense implementation that reflect those early learnings (which aren’t yet fully documented) and which aren’t quite where we want them to be. Although we know there are still likely changes to be made in the implementation, and that there will be some limitations when Suspense is used in React 17, we know Relay Hooks are on the right trajectory for upcoming releases of React, and those changes can be streamlined and allow us to release Relay Hooks a bit earlier.

The Relay Hooks APIs represent the APIs we want to deliver long-term for Relay and which we believe are an improvement over our previous APIs. Even though their underlying implementation is still changing and will likely change more as the Suspense for Data Fetching guidance is documented and finalized by the React team, the Relay Hooks APIs themselves are stable. They have been widely adopted internally, and have been in use in production for over a year, so we are confident that they work. We want to allow the community to start adopting them, and be able to get external feedback from the community as well.

What this means for users adopting Relay Hooks in v11 is:

• There will be some limitations when using Suspense in React 17, which we will document in our release. Specifically, the current release includes a subset of features that work with both synchronous rendering and concurrent rendering. In order to fully support Suspense for Data Fetching, we also need features such as concurrently rendering suspended trees, and transitioning to new trees when data is refetched. The APIs we’re releasing today will allow us to support concurrent rendering with the same APIs in future versions of React.
• When a future version of React is released that fully supports concurrent rendering and Suspense for Data Fetching, Relay will also make a new major release alongside the React release. That release will likely include breaking changes that we will document for the upgrade.

Thanks again for bringing this up, we realize the situation and messaging is a bit confusing, but we hope this helped clarify. I will also be updating our release plan to add more details about our plans in this regard.

[koichik]

@jstejada Thanks for the explanation. It was very clear!