Relay Compiler
graphql
​
The graphql
template tag provided by Relay serves as the mechanism to write queries, fragments, mutations and subscriptions in the GraphQL language. For example:
import {graphql} from 'react-relay';
graphql`
query MyQuery {
viewer {
id
}
}
`;
The result of using the graphql
template tag is a GraphQLTaggedNode
; a runtime representation of the GraphQL document.
Note that graphql
template tags are never executed at runtime. Instead, they are compiled ahead of time by the Relay compiler into generated artifacts that live alongside your source code, and which Relay requires to operate at runtime.
Compiler​
Relay uses the Relay Compiler to convert graphql
literals into generated files that live alongside your source files.
A fragment like the following:
graphql`
fragment MyComponent on Type {
field
}
`
Will cause a generated file to appear in ./__generated__/MyComponent.graphql.js
,
with both runtime artifacts (which help to read and write from the Relay Store)
and Flow types to help you write type-safe code.
The Relay Compiler is responsible for generating code as part of a build step which can then be referenced at runtime. By building the query ahead of time, the Relay's runtime is not responsible for generating a query string, and various optimizations can be performed on the query that could be too expensive at runtime (for example, fields that are duplicated in the query can be merged during the build step, to improve efficiency of processing the GraphQL response).
GraphQL Schema​
To use the Relay Compiler, you need a .graphql
GraphQL Schema file, describing your GraphQL server's API. Typically these files are local representations of a server source of truth and are not edited directly. For example, we might have a schema.graphql
like:
schema {
query: Root
}
type Root {
dictionary: [Word]
}
type Word {
id: String!
definition: WordDefinition
}
type WordDefinition {
text: String
image: String
}
Running the Compiler​
Additionally, you need a directory containing .js
files that use the graphql
tag to describe GraphQL queries and fragments. Let's call this ./src
.
Then run yarn run relay
as set up before.
This will create a series of __generated__
directories that are co-located with the corresponding files containing graphql
tags.
For example, given the two files:
src/Components/DictionaryComponent.js
const DictionaryWordFragment = graphql`
fragment DictionaryComponent_word on Word {
id
definition {
...DictionaryComponent_definition
}
}
`
const DictionaryDefinitionFragment = graphql`
fragment DictionaryComponent_definition on WordDefinition {
text
image
}
`
src/Queries/DictionaryQuery.js
const DictionaryQuery = graphql`
query DictionaryQuery {
dictionary {
...DictionaryComponent_word
}
}
`
This would produce three generated files, and two __generated__
directories:
src/Components/__generated__/DictionaryComponent_word.graphql.js
src/Components/__generated__/DictionaryComponent_definition.graphql.js
src/Queries/__generated__/DictionaryQuery.graphql.js
Importing generated definitions​
Typically you will not need to import your generated definitions. The Relay Babel plugin will then convert the graphql
literals in your code into require()
calls for the generated files.
However the Relay Compiler also automatically generates Flow types as type comments. For example, you can import the generated Flow types like so:
import type {DictionaryComponent_word} from './__generated__/DictionaryComponent_word.graphql';
More rarely, you may need to access a query, mutation, fragment or subscription from multiple files. In these cases, you can also import it directly:
import DictionaryComponent_word from './__generated__/DictionaryComponent_word.graphql';
Is this page useful?
Help us make the site even better by answering a few quick questions.