Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here


Relay is a JavaScript framework for building data-driven React applications.

Subscribe to updates I use relay

Statistics on relay

Number of watchers on Github 10634
Number of open issues 142
Average time to close an issue 6 days
Main language JavaScript
Open pull requests 170+
Closed pull requests 461+
Last commit over 1 year ago
Repo Created over 4 years ago
Repo Last Updated over 1 year ago
Size 19.2 MB
Homepage https://facebook....
Organization / Authorfacebook
Latest Releasev1.5.0
Page Updated
Do you use relay? Leave a review!
View open issues (142)
View relay activity
View on github
Fresh, new opensource launches πŸš€πŸš€πŸš€
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating relay for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Relay Build Status npm version

Relay is a JavaScript framework for building data-driven React applications.

  • Declarative: Never again communicate with your data store using an imperative API. Simply declare your data requirements using GraphQL and let Relay figure out how and when to fetch your data.
  • Colocation: Queries live next to the views that rely on them, so you can easily reason about your app. Relay aggregates queries into efficient network requests to fetch only what you need.
  • Mutations: Relay lets you mutate data on the client and server using GraphQL mutations, and offers automatic data consistency, optimistic updates, and error handling.

See how to use Relay in your own project or check out the community-driven tutorial at Learn Relay.


The relay-examples repository contains an implementation of TodoMVC. To try it out:

git clone
cd relay-examples/todo
npm install
npm run build
npm start

Then, just point your browser at http://localhost:3000.


We actively welcome pull requests, learn how to contribute.


We have a community-maintained list of people and projects using Relay in production.


Relay is MIT licensed.

relay open issues Ask a question     (View All Issues)
  • about 3 years Networklayer issues
  • about 3 years Relay generating invalid query after using `setVariables`
  • about 3 years DefaultNetworkLayer Losing values assigned in Constructor
  • about 3 years Add ability to silence warnings displayed when re-injecting network layer
  • about 3 years dataID.startsWith is not a function
  • about 3 years Two core-js dependencies
  • about 3 years Unable to Typecheck Passed Props
  • about 3 years Add ability to track upload progress of mutations
  • about 3 years RelayContainer: `Relay` was rendered with invalid Relay context `undefined
  • about 3 years Using prepareVariables causing (invalid) warnings
  • about 3 years Bulk actions
  • about 3 years Mutation doesn't include variables i specified in getFatQery function in the response
  • about 3 years Nested create Mutation
  • about 3 years isScalarAndEqual returns true on functions
  • about 3 years Using first/after and last/before together (but not simultaneously)?
  • about 3 years Recommiting a failed transaction throws error
  • about 3 years babel-relay-plugin reference to graphql too tight
  • about 3 years [BIG PROBLEM] Populating an AutoComplete with data from Relay fails
  • about 3 years "this.props.commitUpdate" doesn't work if a new environment is created (login/logout)
  • about 3 years this.props in getOptimisticResponse is cached value
  • about 3 years mutation onFailure do not work on React Native
  • about 3 years Container API : add mutations field
  • about 3 years Send metadata in every query and mutation
  • about 3 years Invariant: "Relay only supports directives with scalar values"
  • about 3 years [meta] Relay 2
  • about 3 years Misleading error message `Uncaught Invariant Violation: RelayQueryNode: Abstract class cannot be instantiated.`
  • about 3 years NODE_DELETE mutation accepts only string for deletedIDFieldName, not an array (path) of strings
  • about 3 years Returning strange alias for connections via REQUIRED_CHILDREN after mutation
  • about 3 years printRelayOSSQuery inlining the values of scalar variables
  • about 3 years Problem with configuration
relay open pull requests (View All Pulls)
  • Add babel package to babel-relay-plugin
  • Run linter against babel-relay-plugin
  • Contextualize RelayRenderer
  • Edit to discribe requirement of babel-cli
  • network layer support for subscriptions
  • Add note for arguments restriction in query
  • Add more detailed error message.
  • Fix import react and relay in the tutorial example
  • First and last arguments must be positive integers
  • Change clientMutationID invariant to a conditional check to work with subscriptions
  • Rename babel plugin
  • Filter records in plural linked fields which are deleted
  • Make babel-relay-plugin run before other transforms
  • Allow variable connection arguments
  • Contextualize RelayNetworkLayer
  • Remove fragmentPointer field from GraphQLStoreQueryResolver
  • Documentation for null initialization of initialVariables
  • Contextualize Relay mutations
  • Override sendMutation via superclass
  • Fixes Windows build error as described at #638
  • [DOCS] Add `introspectionQuery` and `printSchema` illustration for Schema JSON.
  • queued transaction can be also rollbacked
  • Make rangeBehaviors a function
  • Make GraphQLQueryRunner not call diffRelayQueries synchronously
  • Make RelayRenderer run queries after mount
  • RANGE_ADD - Better warning messages when new edge is missing
  • Implement "introduce ship" in relay compontent
  • Start moving readRelayQueryData tests over to use writePayload
  • move range edge reconcile warning to compile time
  • babel plugin: always annotate argument types (including scalars)
  • Support route conditional fragments returning an array
  • Update plugin to Babel 6
  • [WIP][RFC] babel plugin: support mixed identifying/non-identifying root calls
  • Reset store functionality
  • Allow disabling Relay container shouldComponentUpdate
  • Update jest in plugin to 0.10
  • Remove an unnecessary guard
  • Update TodoMVC .babelrc for production builds of RN
  • Add an "indirection layer" to avoid type conflicts
  • RelayFragmentResolver - implement new resolver 1/n
  • Fix the generated GraphQL string in example
  • Upgrade Plugin to use `babel-preset-fbjs`
  • [doc] Using babel-relay-plugin with React Native
  • Upgrade to GraphQL 0.5.0
  • run flow with --profile and --debug
  • Limit the number of Flow workers on Travis CI
  • Fix formatErrors when offset is negative
  • Added missing docs for prepareParams to Relay.Route.
  • Also test node v6 on travis
  • Request for feedback: Add eslint-plugin-graphql to example
  • Stop relying on clientRequestId in graphql response.
  • Added pendingVariables to RelayContainer.
  • Documented all `babel-relay-plugin` options.
  • fix typo in Guides-Mutations
  • Document RelayContainer.getFragment
  • Upgrade fbjs preset
  • Add translation of
  • Update
  • Add missing semi-colon
  • Fix missing close brackets in doc API-Container
  • Fix flow error by fixing the site scoping of suppression comments
  • Link to the release versions of Relay and the plugin in example code
  • Test building the example apps in Travis
  • Add a .babelrc file in scripts/ so they too can know the sweet, sweet taste of ES7
  • Solving issues for relay 0.9 and it examples
  • If fetch error-ed but has a partial response populate the cache.
  • RelayDefaultNetworkLayer, throw Error also on non-200 response.
  • Improve type definition for Higher Order Component
  • Add an example of fetching schema.json from server
  • Fix getRangeBehavior to allow non-string calls
  • add line number
  • Upgrade the TodoMVC example to a version of React Native that contains react-native/pull/7855
  • Parse serialized GraphQL range in getRangeMetadata
  • RANGE_ADD mutation for plain GraphQLLists
  • Update code in the tutorial
  • Expose Relay.QueryConfig as a public method
  • Pass call type in from/toGraphQL
  • Docs: Replace Relay.RootContainer guide with Relay.Renderer
  • Expose injectCacheManager on RelayEnvironment
  • RelayContainer shouldUpdate if there are pendingVariables
  • Upgrade eslint-plugin-flow-vars and fix lint warning
  • Add `Relay.disableQueryCache` static method
  • Include pathToConnection in RANGE_DELETE example on the documentation
  • Range behaviours: Don't warn when value is IGNORE
  • Add a note to setVariables
  • Wrap tracked fragments in their own types to support union types in mutations
  • Add unvalidated RelayQL tag variant
  • Adding Mixcloud to Users list
  • Fixes issue using 'node' as a key in mutation payloads
  • Remove duplicate manual mock
  • Allow @relay(pattern:true) directive on fields with required arguments.
  • Add array path support for deletedIDFieldName in NODE_DELETE mutations
  • Make `enforceSchema` a plugin option
  • Add support to multiple files upload
  • Added link to to README
  • Fixed edge count in test setup
  • Include Link to Star Wars Wiki Page
  • docs(babel): add option info for passPerPreset
  • Allow overriding of formatRequestErrors
  • Fix old links
  • Documentation: Configure plugins on top level in sample .babelrc
  • Add `replaceSchema` method to the `babel-relay-plugin`
  • Add Collibra to
  • remove unnecessary es6 template string in fetch schema doc
  • Build: Fix build by adding missing module mappings.
  • corrects in the doc, parentId is optional when using NODE_DELETE
  • Update
  • Disable entirely eslint for files genareted by the compiler
  • filter null plural fields
  • Support printing ObjectValue arguments
  • Add basic external transformation support to relay-compiler
  • Remove nested Argument variable Invariant
  • Update childContext to include new variables in RefetchContainer
  • Allow passing no callback to PaginationContainer loadMore
  • Create flat bundles using rollup
  • ζ–°ε’ž RelayηΌ–η¨‹ζ€ζƒ³δΈ­ζ–‡εˆηΏ»η¨Ώ
  • Fix deferred queries when root arguments are not of type β€˜ID’
  • Fix #1494 - RelayContainer mutations act on outdated environment
  • Fix scope error in
  • Fix for RelayCompiler watch-mode
  • Fix ReferenceError in mutations docs
  • Generate plural Flow types
  • ViewerHandleTransform ignores viewer w id
  • Add link to more optimistic examples in Todo app
  • Add warning: does not yet work with Android
  • Re-enable tests for QueryRenderer, RefetchContainer, PaginationContainer
  • Add warning: must use QueryRenderer for dynamic initial query
  • Improve relay-compiler error message for mismatched variable types.
  • Remove parent references from RANGE_DELETE in Docs
  • Add lookup prop to QueryRenderer for server side rendering
  • [Docs] Fixes typo in QuickStart guide
  • ISSUE-2042: Update Β«fast-globΒ» package
  • [WIP] Language plugin support.
  • Throw better error for missing idType
  • Cirrus CI config
  • Always generate union types for inline fragment selections
  • Make graphql a peer dependency
  • Add support for client schemas
  • Inflect DataID field from Node interface.
  • Added documentation about the disposable.
  • add option to `relay-compiler` to be quiet
  • fix #2192 - dont recycle frozen objects
  • docs(Introduction): add info about extensions parameter for compiler
  • docs(NetworkLayer): add custom open-source implementations
  • Add docs for @argumentDefinitions and @arguments
  • [WIP] Support babel-macros
  • (Minor) Proposal
  • Bugfix flowtype recursion level
  • Add Caching docs
  • Field is accessible also when @include(if: false)
  • Relax constraint of unique file names in Relay Modern
  • [relay-runtime] Unfreeze JSON object to allow reassignment
  • fixes decorators not working
  • Add for graphql-compiler package
  • Warning when multiple definitions found
  • [Modern] Update refetchContainer example in documentation
  • expose this.props.relay.getVarialbes() to component
  • RFC: Teach compiler `--persist` option
  • Variadic mutations
  • Update
  • Remove a trailing comma in the gulp file which breaks older node builds
  • [Website] Add friday to list of users
  • The FragmentContainer link
  • Update
  • RFC: Support subscriptions and TTL in QueryRenderer
  • [RelayCompilerBin] Don’t include server schema in client extensions.
  • remove overly strict equivalence test
  • Persisted queries
  • Remove the `clientMutationId` requirement by creating a new root id for each executed mutation
relay questions on Stackoverflow (View All Questions)
  • What do 3 dots/periods/ellipsis in a relay/graphql query mean?
  • Which relay objects must implement `Node`?
  • How to manage cursors and sorting in Relay?
  • Implementing `startCursor` and `endCursor` in Relay
  • Updating multiple nodes from a React Relay Mutation
  • How to pass pathName thru query to GraphQL - React-Router Relay GraphQL
  • React relay+router does not collapse queries of nested routes
  • How to transpile a Relay query from TypeScript to ES5?
  • Relay: fetch for recursive data returns null
  • Using Java to access SainSmart 4 Relay with Mac OS 10.8.5 doesn't work
  • using a web service to relay calls to & from another web service in c#
  • How to create User in React-relay/GraphQL
  • Authentication and privileges on Relay/GraphQL
  • Relay mutation expects data fetched by Relay
  • Relay HTTPS requests without decrypting
  • Issue with getting error message from SAP Relay
  • SOLVED relay RISING triggers GPIO event detect on another pin
  • How to tell the user to log in with relay?
  • Relay unicast through RTSP server
  • Forefront TMG and DHCP Relay - requests do not show in logs
  • Relay and redux - initialVariables
  • How do I avoid round-tripping large quantities of data in Relay Mutations?
  • server side rendering with react-router-relay and react-rails
  • Using ES7 decorators with Relay containers
  • I try to implement a connection using relay and all the node's IDs are the same
  • How to execute a relay mutation asynchronously?
  • Using IIS6 to relay mail from Linux RH with smtp
  • Updating React state with Relay
  • What type of Relay mutator configuration is appropriate for inserting a new record?
  • Relay app: How to introspect schema on server?
relay list of languages used
relay latest release notes
v1.5.0 v1.5.0

This release introduces several changes, some of the most relevant ones are highlighted here.


  • Relay Containers are now Flow typed, however Flow types are not yet exported (#2284).
  • Relay Compiler now generates Flow types for GraphQL enum values.
  • Add undocumented support for client-only schema extensions using .graphql files. Extensions only work on existing types, and does not currently support adding client-only types to the schema.
  • Add experimental and undocumented support for QueryRenderer to render directly from store if data is available using new dataFrom prop.
  • Add hooks to enable and disable Relay GC in the store.
  • New ConcreteNode format supporting Batch requests.

Potentially Breaking:

  • Support for client-only schema extensions requires that your GraphQL schema not be inside your the directory you specify as src to the relay-compiler (#2346).
  • Changes the type of RelayNetwork.execute to return a RelayObservable with variables and node, in addition to the QueryPayload. However, RelayNetwork.create maintains the same API (c058ffc4).


  • Fix passing a single item to a list input argument (42c11193).
  • Fix end cursor when fetch returned zero edges in Pagination Container (a17b462b).
  • No longer throw false alarm error in RelayConcreteVariables (03985855).
  • Properly handle complex GraphQL argument literals in the compiler (bb02769f).
  • Calling viewer handler multiple times should not accidentally cause viewer to be null (f442fcd4).
  • Fix issue when using multiple connectionInfo for RANGE_ADD mutation (7f2013d6).
  • Fix issue in Relay Compiler when parsing non-null input (4baa970d).
  • Fix pagination on empty connections (62c8b43f).


  • Ensure the Relay build has run and is not using outdated GraphQL fragments. Optionally this can be turned off in the babel plugin settings (a628637d).
  • Update all callers of react-relay to use CommonJS requires.
  • Speed up getIdentifierForSelection.
  • Compiler doesn't warn on missing fields with abstract types anymore.
  • Relay Compiler now de-duplicates identical objects when generating JSON artifacts which decreases size of artifacts and improves compressability.
  • Disable NoFragmentCyclesRule; can now use Fragments recursively.
  • Remove RecordSourceInspector which is of marginal value, especially now that we have a useful devtools app.
  • Print timing information in compiler verbose mode.
  • Add option to Compiler to be quiet.
  • Upgrade to graphql-js v0.13.0.
  • Upgrade to latest version of fast-glob.
  • Upgrade to babylon7 in Relay Compiler to support new JSX Fragment syntax.
  • Remove graphql.experimental.
  • Several Flow typing improvements.
  • Several documentation fixes.
  • Move test utils to their own package: relay-test-utils.
  • Add support for accessing Components wrapped in a Container in tests.
  • Use jest snapshots for relay-compiler tests.


  • This is the first NPM release to include the MIT license. Read more about this change: (6d87a701de69ce1e271895ff689ddbda2b39b4c2 cherry-picked as 87b4eb6423adbcb4e0d89cfd0eb81a82a7ec33a9)


  • Full support for returning Observable from Relay Network implementations. Use const {Observable} = require('relay-runtime') to use Relay's lightweight Observable implementation which seeks to follow the Observable specification.
  • Support for the new Relay DevTools beta (install with yarn add relay-devtools) (86b63d44a2228705975294d4bfcd34ea2de88f92)
  • Support for latest version of Flow
  • Deprecated graphql.experimental All features now supported directly in graphql literal tags. (9afd76498942ef8c7c8de64c6bfc5b1da2a1dd65)
  • Pagination container now accepts an Observer when loading more data (ef7aa5bf2963d4de592a86109b2bec0a9931b813)

Potentially Breaking:

  • Relay Network and Environment internal APIs renamed to execute() and executeMutation() (0202673f046cd9a52181388c9910ab1e6082e803)
  • Removed legacy flow type generation (8cf10b9f9d670f2723e12a1d2176cba64a2416d4)


  • Case where callback might not be called after mutation (980de6de8a5bb282905e11e4c93feca87eb2e148)
  • Improved printing of queries with @include in classic/compat mode (d65291156865c52e67e6afb0473a07879979b54d)
  • Improved error messages (d8eb6d455a48802080a7acdb7f82dbd4cc4ce47e)
  • Fix case where compiler might not place __typename and id in the correct order (95319d19c2027661efd400eea3137ba7b6885431)
  • Fix deferred queries when root arguments are not of type ID (5ac92718002af0150ecb6a04636a2f70edeb7e74)
  • Fixed remaining issues for compatibility with React v16.
  • Fix passing default arguments to @arguments in compat mode (1ce348a5bc472a58607279c08e2236b8459b5877)
  • Fix issues in QueryRenderer when queries resolve synchronously and immediately (87bfc91055a59654bf4f5f74d5a2fab8de8e947d)
  • Fix case where @argumentDefinitions would not be validated first (50803a5c3951ff7f34fa46bc5ad774fba12dc111)
  • Change readyState to getDefaultState value after retry (beaf5c27117f30ec591ca587bdab0a786903490e)
Other projects in JavaScript