This is an issue to track the differences between the apis exposed in this package and the ones we will expose as part of Relay's react-relay package. Hopefully, this can help the community decide on whether they're safe to adopt and the cost of migration, as well as inform potential changes to the api.
useQuery
useQuery will no longer take environment as an argument. Instead it reads the environment set in context; this also implies that it no longer sets any React context.
useQuery no longer set context, we will expose a new RelayEnvironmentProvider component that takes an environment and sets it in context; variables will no longer be part of context. A RelayEnvironmentProvider should be rendered once at the root of the app, and multiple useQuery's can be rendered under this environment provider.useQuery will now take a fetchPolicy as part of a 3rd configuration argument, to determine whether it should use data cached in the Relay store and whether to send a network request. The options are:
store-or-network (default): Reuse data cached in the store; if the whole query is cached, skip the network requeststore-and-network: Reuse data cached in the store; always send a network request.network-only: Don't reuse data cached in the store; always send a network request. (This is the default behavior of Relay's existing QueryRenderer.store-only: Reuse data cached in the store; never send a network request.useQuery returns a single data object with the query's data, and nothing else.useQuery is integrated with Suspense for rendering loading states. This means that depending on the fetchPolicy, if the query can't render due to missing data (i.e. if the data isn't cached), the query will suspend until the network request completes, and the loading state should be rendered with a Suspense boundary around the query.useQuery will throw an error if an error occurs, which should be caught by a React Error Boundary around the query.useFragment
useFragment will no longer take a "fragment spec" (i.e. a map of keys to fragment definitions). Instead, it will always take a single fragment definition as the first argument, and a fragment reference as the second argument. If multiple fragments need to be used in a single component, useFragment can be used multiple times.useFragment takes a fragment definition and a fragment ref, and returns the data for that fragment. Fragment refs are internal Relay objects that represent pointers to specific instances of the data; e.g. if we have a fragment on the User type, the fragment ref specifies which User, for example User with id 4. The fragment ref is not a new concept; it is the same prop that existing RelayModern containers currently take, only that it is explicitly exchanged for the data inside the component via calling useFragment, instead of that being hidden in the HOC code.useFragment also subscribes to changes in the data, like the HOC version.useFragment is also integrated with Suspense, meaning that if it has any missing data it will suspend until it's parent query completes. This enables rendering of data that is partially cached in the Relay store, or data that has been @defer'd.Pagination and Refetch will have completely separate Hooks APIs (one for pagination, one for refetch), and also integrated with Suspense. They will be quite different from the apis exposed here as configuration to useFragment, so the migration cost might be higher if the api from this repo is adopted.
Mutations and Subscriptions will also have completely separate Hooks APIs, and will also integrated with Suspense; the details of what the right APIs with Suspense will be are still under consideration.
Backwards CompatibilityEverything will be released in a backwards compatible way, meaning that new Relay Hooks will work with existing containers. Note that as of Relay v5.0.0 (will be released in the coming days), our existing RelayModern containers will no longer consume variables from context, but instead consume variables via fragment ownership. As mentioned before, Relay context will no longer contain variables; only an environment.
sorenhoyer, tlvenn, mrtnzlml, brunolemos, minheq and 5 morealunyov, navilan, otofu-square, AlicanC, spyl94 and 18 more
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4