Relay is a JavaScript framework for building data-driven React applications.
MIT License
Bot releases are hidden (Show)
Published by captbaritone 17 days ago
Following up from our v18.0.0 release last month, v18.1.0 provides a number of fixes and improvements, adds some new experimental APIs, and ships some long-running experimental features as stable.
For the past several years we've been iterating on Relay Resolvers which provided a structured and typesafe way to model client state and derived data in your GraphQL graph. As of this release, Relay Resolvers are enabled by default and no-longer experimental. As part of this stabilization we shipped fixes for Relay Resolvers when used with TypeScript and fixed a few edge cases related to how errors encountered by resolvers are handled.
We released @catch
in v18.0.0 and are very excited about the capabilities it enables. Check out Itamar Kestenbaum's GraphQL conf talk about it here: Build Confidently: How @Catch and Error Handling Pave Way in Field Nullability.
Since that release we've made a few improvements:
@catch
directive that are marked as @semanticNonNull
in the schema now generate non-nullable TypeScript/Flow types. See semantic nullability.@catch
no-longer include the error message. This is because GraphQL error messages are generally not safe to show to users. These error messages can still be accessed by the field logger provided to your Relay Environment. In the future we plan to let users opt into allowing safe error messages through to product code.We've improved how errors are reported by the Relay compiler to ensure we report as many errors as possible, and each error includes sufficient context.
Our VSCode extension now includes a command to quickly copy the full text of a query directly from within your editor.
In some cases it can be useful to read a fragment outside of a React hook. However, doing this requires handling a number of concerns.
@defer
or Relay Resolver suspense).@throwOnFieldError
, @required(action: THROW)
)To enable users to read fragment data while correctly handling these cases, we've added two experimental APIs:
observeFragment
: Read a fragment as a stream of states where each state might be loading, error, or value.waitForFragmentData
: Read a fragment as a promise which will resolve when data is available, or reject if an error is encountered.Thanks to members of our community for submitting pull requests to improve our docs:
We are always continuing to evolve and improve Relay. These changes are part of features or implementations which are either in progress or are being experimented with internally.
Published by captbaritone about 1 month ago
With version 18, the Relay team at Meta and our community of contributors have made several significant improvements to Relay:
@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.Read all about them in more detail below:
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"
}
}
}
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.
@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.
@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
@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
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.
Read more about Resolver context
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.
Thanks to Tobias Tengler, Relay's editor support now includes:
IdOf
by Tianyu YaoThere were over 100 additional commits since our last release which have been omitted from this doc
Since our last release in January of this year, we've made many improvements to Relay. Themes include:
Relay compiler now runs spec-compliant schema validation against your schema including client schema extensions and Relay Resolvers. You can opt out of this feature by disabling validation in your Relay compiler config.
// relay.config.json
{
//...
"featureFlags": {
"disable_schema_validation": true
}
}
[ccc4465e6a47] by Jordan Eldredge
We now validate that the names passed to directives like @prependNode
and @appendNode
are valid typenames. You can opt out of this validation with the following feature flag in your compiler config:
// relay.config.json
{
//...
"featureFlags": {
"disable_edge_type_name_validation_on_declerative_connection_directives": {
"kind": "enabled"
}
}
}
[53b24361bb4d] by tobias-tengler
This release includes a new implementation of our hooks which are significantly more efficient in terms of memory use. Thanks to Dave McCabe for his work on this huge project.
Huge shout out to community contributor Tobias Tengler for many improvements to our Editor Support via our VSCode extension. Our VSCode extension is powered by the relay-compiler
so upgrading to version 17.0.0
of the compiler should unlock a number of great IDE features.
watchman_query_time_before_subscribe
by Tianyu Yaowatchman_query_time_before_subscribe
by Tianyu YaopreferFetchable
argument to the @refetchable directive by Andrey Lunyovnode
query generation in @refetchable by Andrey LunyovpreferFetchable
argument by Andrey LunyovReactTestUtils
by Tim YungWe are also continuing to evolve many experimental features which are not yet stable enough to be enabled by default in Relay.
Relay Resolvers have been extended to support defining types which implement interfaces, and define resolvers that return client-defined interfaces where all implementing types are defined using Relay Resolvers. Relay Resolvers are now stable enough to have full documentation with instructions on how to enable them.
IdOf<>
return type by Tianyu YaoWe've added an experimental new directive to allow fragments to appear as fields. This can enable you, or optionally require you, to check if a fragment was fetched before using it.
As part of our involvement with the GraphQL Nullability Working Group we are exploring features to enable explicit error handling and semantic nullability. Neither of these features are officially available yet, but we're excited about what will become possible here.
Published by alunyov 9 months ago
This change is a breaking change, as the customScalars
config option in the single-project config must now be specified as customScalarTypes
.
Parameters
and indexed access type to extract PreloadParams by Sam Zhoudirectives
argument for @refetchable
(#4520) by Daniel Lo NigroFull Changelog: https://github.com/facebook/relay/compare/v16.1.0...v16.2.0
Published by alunyov 10 months ago
enable_strict_custom_scalars
to perform validations when custom scalar types are used, to check that the user doesn't try to pass literal values (strings, ints, etc) in positions where a custom scalar type is expected, as this can break type safety since Relay can't know whether those literals conform to the underlying custom type.EntryPointElementConfig
by Sam ZhouuseFragmentInternal
to use in useLazyLoadQueryNode
by Andrey LunyovPublished by monicatang about 1 year ago
@connection
directive will now throw if they are invalid instead of being a no-op. [2dd79543d3f6]Flow-related breaking changes:
commitMutation
[603ce546741a] and useMutation
[051e4694c20b].RelayModernRecord.js
. [21a896c54e63]babel-plugin-syntax-hermes-parser
plugin, which switches Babel to use hermes-parser
instead of @babel/parser
, and enables full syntax support for Flow. [c320a892482c]React.Element
fully opaqueTypeScript-related breaking changes:
Record<PropertyKey, never>
instead of as {}
to represent an object without properties. [16910c948e9a] (#4404)null
and undefined
(T | null | undefined
) instead of (T | null
). To keep the old type generation behavior for now, you may set the typescriptExcludeUndefinedFromNullableUnion
feature flag in the relay-compiler
config as follows. {
"language": "typescript",
"typescriptExcludeUndefinedFromNullableUnion": true
}
Relay Resolvers are an experimental feature of Relay which allows you to model derived data, and soon client state, in your Relay graph. Since our last release we’ve put considerable work into stabilizing the feature. This includes bug fixes across our compiler, type generation, runtime and LSP (editor integration). In particular, contributors have fixed a number of bugs which made it impossible to use Relay Resolvers with TypeScript.
Documentation:
Improvements:
@required
to bubble to client edge resolvers.@live
field@weak
resolver values were getting normalized@weak
model resolvers@rootFragment
on model types@rootFragment
on model types@required
on client edges@defer
/@stream
names (#4467)Additions:
Typo fixes:
useTransistion
getting-started/installation-and-setup.md
(#4306)Tutorial updates:
Other corrections:
readInlineData
function (#4451)useMemo()
in docs (#4281)cannotReadPropertyOfUndefined
experimental.abstract_locations
configinference_mode
config now that LTI is the defaultTPreloadParams
invariant$Shape
to Partial
in Relay files, suppressing errorsPublished by captbaritone over 1 year ago
Record
(which is an untyped grabbag containing whatever the store has), we instead pass a ?ReadOnlyRecordProxy
. Furthermore, we replace NormalizationLinkedField
with CommonLinkedField
, which both a ReaderLinkedField
and NormalizationLinkedField
"implement".flow
for graphql
tags. [a75a445bb72c] [ef29f061fd3a] [78bd12d39562] [614c74718544] [ab9f04ab54ea]@weak
objects@weak
types in docblocksimport type
for named imports in typescriptimport type
in typescript for all imports (#4029)assignClientAbstractTypes
to the DataCheckerjs
fields in query for 3D when local import is enabledRelay v14.1.0 adds improvements for existing relay features - primarily fixes and feature compatibility for client extensions and @inline
. Thanks to our open source contributors who helped us release the Relay VSCode Extension!
[cefab9e1659f] Support for @required
and client-edges
[90ccda1da4b0] Support @argumentDefinitions
in @inline
fragments (#3935)
[8adcfab3ec11] VS Code: Find references of the Resolver field.
[b965299349d1] useClientQuery hook
[7d5cc3431891] Add support for resolvers without fragments
[8db002fa4120] Support custom scalar arguments that are passed as literals
[a5d67d6bf677] Add resolvers to the dependency graph (Fix missing resolver fragments in incrmental mode and VS Code)
[57f96a133177] Improve error message when you mix up @live
and non-live values.
[c4dbd26278fa] Remove .js
and .ts
from require / import (#4002)
[cd1e9ae06d11] Fix MutationHandlers on field with args
[7e6dbdd6af74] Ensure only one implemntation on interface
[055908fb12a2] VS Code: Fix comment blocks to recognize the embedded language inside of a JS file. (#4001)
[6a9b0e560e3d] Performance optimizations in the validate_conflicting_selections
[fa5a3baa9a8d] Explicitly enumerate unsupported ReaderNode types
[9990e6f0bf79] Disallow default values on resolver fields
[d42bb7c5a139] VSCode extension pathToRelay doesn't allow relative paths (#3969)
[a86323f43c59] Validate conflicting selections in client fields
Published by alunyov over 2 years ago
src
, schema
, artifactDirectory.
This simplifies the public API of the compiler. The error message should print helpful message with possible config file, that can be used instead of these CLI
arguments.language
configuration option required. In v13, we have default language as flow
(or Javascript with Flow comments) for reading and generating artifacts. Majority of the projects in OSS, however, use typescript
- in order to detect which language (typescript, JS, or flow) is used in the project we will use this option.__typename
in fragments on query.__typename
selections within concrete linked fields have a string literal type, instead of the type string
.typegen_phase
have been removed from the Relay compiler config.readUpdatableQuery_EXPERIMENTAL
and readUpdatableFragment_EXPERIMENTAL
@inline
fragments (#3933).@no_inline
(#3923).CustomScalarType
to represent custom scalar types in the Relay compiler configuration.sha256
and md5
for local file persister (#3878)@required
on plural fragments.@inline
fragments.graphql
tag and template. literal.Full Changelog: https://github.com/facebook/relay/compare/v13.2.0...v14.0.0
Published by voideanvalue over 2 years ago
Published by alunyov over 2 years ago
typegenPhase
in the single project config file. See release v13.1.0 for more details.Full Changelog: https://github.com/facebook/relay/compare/v13.1.0...v13.1.1
Published by kassens over 2 years ago
"flowTypegen": "Compat"
but projects should migrate to using the updated names (e.g. MyFragment$fragmentType
instead of MyFragment$ref
.Published by alunyov over 2 years ago
__isX
fieldsIgnore
. To keep some files in __generated__
(or in artifactDirectory) directoriesworker_count
from the OperationPersister interfacecommon/rust/cargo_from_buck/bin/autocargo
detail
fieldFull Changelog: https://github.com/facebook/relay/compare/v13.0.2...v13.0.3
Published by alunyov over 2 years ago
global
before usage (#3646)import
instead of require
if eager_es_modules = true---validate
CLI option (#3771)persistConfig.params
id
field name from schema_config in relay-typegennpx prettier
on README filesrelay-compiler
common/rust/cargo_from_buck/bin/autocargo
@waterfall
directive@waterfall
to Client Edge fields@required
within Resolvers@required
resolver values@required
for Relay ResolversThank you to all contributors who helped with this release!
Special thanks to @ch1ffa for adding many valuable fixes and improvements!
Full Changelog: https://github.com/facebook/relay/compare/v13.0.1...v13.0.2
Published by alunyov almost 3 years ago
extensions
in config.Full Changelog: https://github.com/facebook/relay/compare/v13.0.0...v13.0.1
Published by alunyov almost 3 years ago
relay-compiler
is now implemented in Rust and it replaced the JS version from v12.
LOG
, THROW
, or bubble (NONE
) null fields.flow
for graphql
tags. It may break some of the components that rely on the structure of the generated Relay flow-types.commitLocalUpdate
; it is now derived from the shape of the mutation and is optional. This type had previously been typed as $FlowFixMe
(i.e. any
); as a result, adding static types here is a breaking change.relay-config
.For more details see:
Changes since RC.2
Node
interface id
field to be configurable. (#3638)include
option to single project config file, and warn if it is used.Published by alunyov almost 3 years ago
To install this version, run:
npm install react-relay@dev relay-runtime@dev
npm install --save-dev relay-compiler@dev babel-plugin-relay@dev
Or using yarn:
yarn add relay-runtime@dev react-relay@dev
yarn add --dev relay-compiler@dev babel-plugin-relay@dev
main
to NPM (#3709)connection_interface
on the project_config
ProjectConfig
and some other things to relay-config
Typesafe Updaters: Add support for client schema extension fields. Typesafe updaters is an unreleased, experimental project to provide a more ergonomic, typesafe interface for writing updaters.
Published by alunyov almost 3 years ago
To install this version, run:
npm install react-relay@dev relay-runtime@dev
npm install --save-dev relay-compiler@dev babel-plugin-relay@dev
Or using yarn:
yarn add relay-runtime@dev react-relay@dev
yarn add --dev relay-compiler@dev babel-plugin-relay@dev
artifactsDirectory
(#3675) [bc03126af3a]relay-config
(#3678) [4c5ddec8f3d]Published by alunyov almost 3 years ago
The one with compiler implemented in Rust.
For reference, see the issue: https://github.com/facebook/relay/issues/3180
To install this version, run:
npm install react-relay@dev relay-runtime@dev
npm install --save-dev relay-compiler@dev babel-plugin-relay@dev
Or using yarn:
yarn add relay-runtime@dev react-relay@dev
yarn add --dev relay-compiler@dev babel-plugin-relay@dev
relay-compiler
is now implemented in Rust and it replaced the JS version from v12.
@required
directive: Improve the ergonomics of handling null values by declaratively telling Relay to either LOG
, THROW
, or bubble (NONE
) null fields. See more: https://relay.dev/docs/next/guides/required-directive/
@no_inline
: Disable inlining the fragment when it is used in normalization(query) artifacts. Reduce generated artifacts size if the fragment is used in many places.flow
for graphql
tags.
ReaderInlineDataFragment
to GraphQLTaggedNode
commitLocalUpdate
; it is now derived from the shape of the mutation and is optional. This type had previously been typed as $FlowFixMe
(i.e. any
); as a result, adding static types here is a breaking change.
@required
docs publicreadUpdatableQuery_EXPERIMENTAL
method which allows developers to update data in the store using regular assignment, instead of the existing store mutation APIs.Full Changelog: https://github.com/facebook/relay/compare/v12.0.0...v13.0.0-rc.0
Published by alunyov about 3 years ago
Commits: https://github.com/facebook/relay/compare/v11.0.2...main
This is release contains a long list of new fixes and additions to Relay that was added in the last few months: runtime optimizations, react integration updates, logger updates, internal type-safety, documentation updates, and more.
It also contains a few small, but possibly, breaking changes. One of which is related to the Abstract Type Refinement, others to the live query behavior.
The Relay team is continuing work on the new rust-version of the compiler, and VS Code extension. As well as experimenting with the new features: multi-environment runtime support, advanced client-state management APIs. We hope to include these in the upcoming releases.
Thanks to all contributors for your work and support!
false
by default, but true
in internal configuration [2732db54335].getPaginationMetadata, getPaginationVariables, getRefetchMetadata, getValueAtPath, type Direction
[3b6f70d85fb]._processModuleImportPayload
.falsy
conditions and @skip.environment.lookup
when not needed in QueryResource.applyMutation
.lodash
from 4.17.20 to 4.17.21 in /packages/babel-plugin-relay (#3482).path-parse
from 1.0.6 to 1.0.7 in /packages/babel-plugin-relay (#3559).