Compiler Configuration
Compiler Config Options​
For information about where the Relay compiler looks for its config file, or a minimal config, see the Relay Compiler page.
If you need more advanced options of the Relay Compiler Config, the exhaustive full schema can be found below. The shape of the Relay Compiler Config is given as ConfigFile. Note that while the shapes are documented in pseudo TypeScript, the compiler is parsing them in Rust so some subtle differences may exist.
tip
Install the Relay VSCode extension to get autocomplete, hover tips, and type checking for the options in your Relay config.
Config File
Relay's configuration file. Supports a single project config for simple use cases and a multi-project config for cases where multiple projects live in the same repository. In general, start with the SingleProjectConfigFile.
// Base case configuration (mostly of OSS) where the project have single schema, and single source directory
| SingleProjectConfigFile // Relay can support multiple projects with multiple schemas and different options (output, typegen, etc...). This MultiProjectConfigFile is responsible for configuring these type of projects (complex)
| MultiProjectConfigFileConfig File Project
// If a base project is set, the documents of that project can be referenced, but won't produce output artifacts. Extensions from the base project will be added as well and the schema of the base project should be a subset of the schema of this project.
base?: ProjectName | null
// Name of the command that runs the relay compiler. This will be added at the top of generated code to let readers know how to regenerate the file.
codegenCommand?: string | null
// A map from GraphQL error name to import path, example: {"name:: "MyErrorName", "path": "../src/MyError"}
customErrorType?: CustomTypeImport | null
// A map from GraphQL scalar types to a custom JS type, example: { "Url": "String" } { "Url": {"name:: "MyURL", "path": "../src/MyUrlTypes"} }
// Threshold for diagnostics to be critical to the compiler's execution. All diagnostic with severities at and below this level will cause the compiler to fatally exit.
// This option enables opting out of emitting es modules artifacts. When set to false, Relay will emit CommonJS modules.
eagerEsModules?: boolean = true
// When set, enum values are imported from a module with this suffix. For example, an enum Foo and this property set to ".test" would be imported from "Foo.test". Note: an empty string is allowed and different from not setting the value, in the example above it would just import from "Foo".
enumModuleSuffix?: string | null
// Some projects may need to exclude files with certain extensions.
excludesExtensions?: array | null
// A placeholder for allowing extra information in the config file
extra?: any
// Some projects may need to generate extra artifacts. For those, we may need to provide an additional directory to put them. By default the will use `output` *if available
extraArtifactsOutput?: string | null
// Enable and disable experimental or legacy behaviors. WARNING! These are not stable and may change at any time.
featureFlags?: FeatureFlags | null
// Import/export style to use in generated JavaScript modules.
// The desired output language, "flow" or "typescript".
language?: "javascript" | "typescript" | "flow"
// Configuration for the @module GraphQL directive.
moduleImportConfig?: ModuleImportConfig = {
dynamicModuleProvider: null,
operationModuleProvider: null,
surface: null,
} // This option controls whether or not a catch-all entry is added to enum type definitions for values that may be added in the future. Enabling this means you will have to update your application whenever the GraphQL server schema adds new enum values to prevent it from breaking.
noFutureProofEnums?: boolean
// When set, generated input types will have the listed fields optional even if the schema defines them as required.
optionalInputFields?: string[] = []
// A project without an output directory will put the generated files in a __generated__ directory next to the input file. All files in these directories should be generated by the Relay compiler, so that the compiler can cleanup extra files.
output?: string | null
// If this option is set, the compiler will persist queries using this config.
persist?: PersistConfig | null
// Whether to treat all JS module names as relative to './' (true) or not. default: true
relativizeJsModulePaths?: boolean = true
// Require all GraphQL scalar types mapping to be defined, will throw if a GraphQL scalar type doesn't have a JS type
requireCustomScalarTypes?: boolean
// Indicates the type to import and use as the context for Relay Resolvers.
resolverContextType?: ResolverContextTypeInput | null
resolversSchemaModule?: ResolversSchemaModuleConfig | null
// A generic rollout state for larger codegen changes. The default is to pass, otherwise it should be a number between 0 and 100 as a percentage.
rollout?: integer | null
// Path to the schema.graphql or a directory containing a schema broken up in multiple *.graphql files. Exactly 1 of these options needs to be defined.
schema?: string | null
// Extra configuration for the GraphQL schema itself.
schemaConfig?: SchemaConfig = {
connectionInterface: {
cursor: "cursor",
edges: "edges",
endCursor: "endCursor",
hasNextPage: "hasNextPage",
hasPreviousPage: "hasPreviousPage",
node: "node",
pageInfo: "pageInfo",
startCursor: "startCursor",
}, deferStreamInterface: {
deferName: "defer",
ifArg: "if",
initialCountArg: "initialCount",
labelArg: "label",
streamName: "stream",
useCustomizedBatchArg: "useCustomizedBatch",
}, enableTokenField: false,
nodeInterfaceIdField: "id",
nodeInterfaceIdVariableName: "id",
nonNodeIdFields: null,
unselectableDirectiveName: "unselectable",
}schemaDir?: string | null
// Directory containing *.graphql files with schema extensions.
schemaExtensions?: string[] = []
// Schema name, if differs from project name. If schema name is unset, the project name will be used as schema name.
schemaName?: string | null
// If `output` is provided and `shard_output` is `true`, shard the files by putting them under `{output_dir}/{source_relative_path}`
shardOutput?: boolean
// Regex to match and strip parts of the `source_relative_path`
shardStripRegex?: string | null
// Optional regex to restrict @relay_test_operation to directories matching this regex. Defaults to no limitations.
testPathRegex?: string | null
// Keep the previous compiler behavior by outputting an union of the raw type and null, and not the **correct** behavior of an union with the raw type, null and undefined.
typescriptExcludeUndefinedFromNullableUnion?: boolean
// Whether to use the `import type` syntax introduced in Typescript version 3.8. This will prevent warnings from `importsNotUsedAsValues`.
useImportTypeSyntax?: boolean
// Generates a `// @relayVariables name1 name2` header in generated operation files
variableNamesComment?: boolean
Connection Interface
Configuration where Relay should expect some fields in the schema.
cursor?: string
edges?: string
endCursor?: string
hasNextPage?: string
hasPreviousPage?: string
node?: string
pageInfo?: string
startCursor?: string
Custom Type
Defines a custom GraphQL descrbing a custom scalar.
// A string representing the name of a custom type. e.g. "string" or "number"
| string // A module which defines the custom type. e.g. { "name": "MyCustomType", "path": "./Types.ts" }
| CustomTypeImportCustom Type Import
Defines a module path and export name of the Flow or TypeScript type descrbing a GraphQL custom scalar.
// The name under which the type is exported from the module
name?: string
// The path to the module relative to the project root
path?: string
Defer Stream Interface
Configuration where Relay should expect some fields in the schema.
deferName?: string
ifArg?: string
initialCountArg?: string
labelArg?: string
streamName?: string
useCustomizedBatchArg?: string
Diagnostic Level
Levels for reporting errors in the compiler.
// Report only errors
| "error" // Report diagnostics up to warnings
| "warning" // Report diagnostics up to informational diagnostics
| "info" // Report diagnostics up to hints
| "hint"Diagnostic Report Config
Configuration for all diagnostic reporting in the compiler
// Threshold for diagnostics to be critical to the compiler's execution. All diagnostic with severities at and below this level will cause the compiler to fatally exit.
criticalLevel?: DiagnosticLevel
Feature Flag
// Fully disabled: developers may not use this feature
| {kind: "disabled"
} // Fully enabled: developers may use this feature
| {kind: "enabled"
} // Partially enabled: developers may only use this feature on the listed items (fragments, fields, types).
| {allowlist: string[]
kind: "limited"
} // Partially enabled: used for gradual rollout of the feature
| {kind: "rollout"
rollout: integer | null
} // Partially enabled: used for gradual rollout of the feature
| {kind: "rolloutrange"
rollout: RolloutRange
}Feature Flags
// @required with an action of THROW is read-time feature that is not compatible with our mutation APIs. We are in the process of removing any existing examples, but this flag is part of a process of removing any existing examples.
// Allow non-nullable return types from resolvers.
// Relay Resolvers are a read-time feature that are not actually handled in our mutation APIs. We are in the process of removing any existing examples, but this flag is part of a process of removing any existing examples.
// Print queries in compact form
// Skip the optimization which extracts common JavaScript structures in generated artifacts into numbered variables and uses them by reference in each position in which they occur.
This optimization can make it hard to follow changes to generated code, so being able to disable it can be helpful for debugging.
To disable deduping for just one fragment or operation's generated artifacts:
```json "disable_deduping_common_structures_in_artifacts": { { "kind": "limited", "allowList": ["<operation_or_fragment_name>"] } } ```
// Disable validation of the `edgeTypeName` argument on `@prependNode` and `@appendNode`.
disable_edge_type_name_validation_on_declerative_connection_directives?: FeatureFlag = {
kind: "disabled",
} // Disable full GraphQL argument type validation. Historically, we only applied argument type validation to the query that was actually going to be persisted and sent to the server. This meant that we didn't typecheck arguments passed to Relay Resolvers or Client Schema Extensions.
We also permitted an escape hatch of `uncheckedArguments_DEPRECATED` for defining fragment arguments which were not typechecked.
We no-longer support `uncheckedArguments_DEPRECATED`, and we typecheck both client and server arguments. This flag allows you to opt out of this new behavior to enable gradual adoption of the new validations.
This flag will be removed in a future version of Relay.
// Mirror of `enable_resolver_normalization_ast` excludes resolver metadata from reader ast
disable_resolver_reader_ast?: boolean
// Disable validating the composite schema (server, client schema extensions, Relay Resolvers) after its built.
disable_schema_validation?: boolean
enable_3d_branch_arg_generation?: boolean
// Allow per-query opt in to normalization AST for Resolvers with exec_time_resolvers directive. In contrast to enable_resolver_normalization_ast, if this is true, a normalization AST can be generated for a query using the @exec_time_resolvers directive
enable_exec_time_resolvers_directive?: boolean
// Add support for parsing and transforming variable definitions on fragment definitions and arguments on fragment spreads.
enable_fragment_argument_transform?: boolean
// Allow relay resolvers to extend the Mutation type
enable_relay_resolver_mutations?: boolean
// Fully build the normalization AST for Resolvers
enable_resolver_normalization_ast?: boolean
// Perform strict validations when custom scalar types are used
enable_strict_custom_scalars?: boolean
// Enforce that you must add `@alias` to a fragment if it may not match, due to type mismatch or `@skip`/`@include`
// The `path` field in `@required` Reader AST nodes is no longer used. But removing them in one diff is too large of a change to ship at once.
This flag will allow us to use the rollout FeatureFlag to remove them across a number of diffs.
// For now, this also disallows fragments with variable definitions This also makes @module to opt in using @no_inline internally NOTE that the presence of a fragment in this list only controls whether a fragment is *allowed* to use @no_inline: whether the fragment is inlined or not depends on whether it actually uses that directive.
// Skip generating resolver type assertions for resolvers which have been derived from TS/Flow types.
// Feature flag to prefer `fetch_MyType()` generatior over `node()` query generator in @refetchable transform
prefer_fetchable_in_refetch_queries?: boolean
// Enable generation of text artifacts used to generate full query strings later.
// Generate the `moduleImports` field in the Reader AST.
Js Module Format
Formatting style for generated files.
// Common JS style, e.g. `require('../path/MyModule')`
| "commonjs" // Facebook style, e.g. `require('MyModule')`
| "haste"Local Persist Config
Configuration for local persistence of GraphQL documents. This struct contains settings that control how GraphQL documents are persisted locally.
// The algorithm to use for hashing the operation text.
algorithm?: "MD5" | "SHA1" | "SHA256" = "MD5"
// The file path where the persisted documents will be written.
file?: string
// Whether to include the query text in the persisted document.
include_query_text?: boolean
Module Import Config
Configuration for @module.
// Defines the custom import statement to be generated on the `ModuleImport` node in ASTs, used for dynamically loading components at runtime.
dynamicModuleProvider?: ModuleProvider | null
// Defines the custom import statement to be generated for the `operationModuleProvider` function on the `NormalizationModuleImport` node in ASTs. Used in exec time client 3D.
operationModuleProvider?: ModuleProvider | null
// Defines the surface upon which @module is enabled.
surface?: "resolvers" | "all" | null
Module Provider
// Generates a module provider using JSResource
| {mode: "JSResource"
} // Generates a custom JS import, Use `<$module>` as the placeholder for the actual module. e.g. `"() => import('<$module>')"`
| {mode: "Custom"
statement: string
}Multi Project Config File
Schema of the compiler configuration JSON file.
// The user may hard-code the JSON Schema for their version of the config.
$schema?: string | null
codegenCommand?: string | null
// Glob patterns that should not be part of the sources even if they are in the source set directories.
excludes?: string[] = ["**/node_modules/**", "**/__mocks__/**", "**/__generated__/**"]
// Enable and disable experimental or legacy behaviors. WARNING! These are not stable and may change at any time.
featureFlags?: FeatureFlags = {
actor_change_support: {
kind: "disabled",
}, allow_required_in_mutation_response: {
kind: "disabled",
}, allow_resolver_non_nullable_return_type: {
kind: "disabled",
}, allow_resolvers_in_mutation_response: {
kind: "disabled",
}, compact_query_text: {
kind: "disabled",
}, disable_deduping_common_structures_in_artifacts: {
kind: "disabled",
}, disable_edge_type_name_validation_on_declerative_connection_directives: {
kind: "disabled",
}, disable_full_argument_type_validation: {
kind: "disabled",
}, disable_resolver_reader_ast: false,
disable_schema_validation: false,
enable_3d_branch_arg_generation: false,
enable_exec_time_resolvers_directive: false,
enable_fragment_argument_transform: false,
enable_relay_resolver_mutations: false,
enable_resolver_normalization_ast: false,
enable_strict_custom_scalars: false,
enforce_fragment_alias_where_ambiguous: {
kind: "disabled",
}, legacy_include_path_in_required_reader_nodes: {
kind: "disabled",
}, no_inline: {
kind: "disabled",
}, omit_resolver_type_assertions_for_confirmed_types: {
kind: "disabled",
}, prefer_fetchable_in_refetch_queries: false,
relay_resolver_enable_interface_output_type: {
kind: "disabled",
}, skip_printing_nulls: {
kind: "disabled",
}, text_artifacts: {
kind: "disabled",
}, use_reader_module_imports: {
}kind: "disabled",
}, // Similar to sources but not affected by excludes.
header?: string[] = []
// Then name of the global __DEV__ variable to use in generated artifacts
isDevVariableName?: string | null
// Optional name for this config, might be used for logging or custom extra artifact generator code.
name?: string | null
// Opt out of source control checks/integration.
noSourceControl?: boolean | null
// Configuration of projects to compile.
projects?: { [key: string]: ConfigFileProject }
// Root directory relative to the config file. Defaults to the directory where the config is located.
root?: string | null
// Watchman saved state config.
savedStateConfig?: ScmAwareClockData | null
// A mapping from directory paths (relative to the root) to a source set. If a path is a subdirectory of another path, the more specific path wins.
sources?: { [key: string]: ProjectName | ProjectName[] }
Non Node Id Fields Config
Configuration of Relay's validation for `id` fields outside of the `Node` interface.
// A map of parent type names to allowed type names for fields named `id`
allowedIdTypes?: { [key: string]: string } = {}
Persist Config
Configuration for how the Relay Compiler should persist GraphQL queries.
// This variant represents a remote persistence configuration, where GraphQL queries are sent to a remote endpoint for persistence.
| RemotePersistConfig // This variant represents a local persistence configuration, where GraphQL queries are persisted to a local JSON file.
When this variant is used, the compiler will attempt to read the local file as a hash map, add new queries to the map, and then serialize and write the resulting map to the configured path.
| LocalPersistConfigProject Name
Represents the name of a project in the Relay configuration.
// No project name is specified.
| null // A project name.
This should match one the keys in the `projects` map in the Relay compiler config.
| stringRemote Persist Config
Configuration for remote persistence of GraphQL documents.
// Number of concurrent requests that can be made to the server.
concurrency?: integer | null
// Additional headers to include in the POST request.
headers?: { [key: string]: string } = {}
// Whether to include the query text in the persisted document.
includeQueryText?: boolean
// Additional parameters to include in the POST request.
The main document will be in a POST parameter `text`. This map can contain additional parameters to send.
params?: { [key: string]: string } = {}
// URL that the document should be persisted to via a POST request.
url?: string
Resolver Context Type Input
Describes the type to import and use as the context for Relay Resolvers.
// The type imported using a relative path
| ResolverContextTypeInputPath // The type imported using a named package
| ResolverContextTypeInputPackageResolver Context Type Input Package
Specifies how Relay can import the Resolver context type from a named package
// The name under which the type is exported from the package
name?: string
// The name of the package
package?: string
Resolver Context Type Input Path
Specifies how Relay can import the Resolver context type from a path
// The name under which the type is exported from the module
name?: string
// The path to the module relative to the project root
path?: string
Resolvers Schema Module Config
Configuration for resolvers_schema_module generation
applyToNormalizationAst?: boolean
path?: string
Rollout Range
A utility to enable gradual rollout of large codegen changes. Allows you to specify a range of percentages to rollout.
end?: number
start?: number
Saved State Clock Data
Holds extended clock data that includes source control aware query metadata. <https://facebook.github.io/watchman/docs/scm-query.html>
commit-id?: string | null
config?: true
storage?: string | null
Schema Config
connectionInterface?: ConnectionInterface = {
cursor: "cursor",
edges: "edges",
endCursor: "endCursor",
hasNextPage: "hasNextPage",
hasPreviousPage: "hasPreviousPage",
node: "node",
pageInfo: "pageInfo",
startCursor: "startCursor",
}deferStreamInterface?: DeferStreamInterface = {
deferName: "defer",
ifArg: "if",
initialCountArg: "initialCount",
labelArg: "label",
streamName: "stream",
useCustomizedBatchArg: "useCustomizedBatch",
} // If we should select __token field on fetchable types
enableTokenField?: boolean
// The name of the `id` field that exists on the `Node` interface.
nodeInterfaceIdField?: string = "id"
// The name of the variable expected by the `node` query.
nodeInterfaceIdVariableName?: string = "id"
nonNodeIdFields?: NonNodeIdFieldsConfig | null
// The name of the directive indicating fields that cannot be selected
unselectableDirectiveName?: string = "unselectable"
Scm Aware Clock Data
Holds extended clock data that includes source control aware query metadata. <https://facebook.github.io/watchman/docs/scm-query.html>
Single Project Config File
// The user may hard-code the JSON Schema for their version of the config.
$schema?: string | null
// A specific directory to output all artifacts to. When enabling this the babel plugin needs `artifactDirectory` set as well.
artifactDirectory?: string | null
// Name of the command that runs the relay compiler. This will be added at the top of generated code to let readers know how to regenerate the file.
codegenCommand?: string | null
// A map from GraphQL error name to import path, example: {"name:: "MyErrorName", "path": "../src/MyError"}
customErrorType?: CustomTypeImport | null
// A map from GraphQL scalar types to a custom JS type, example: { "Url": "String" } { "Url": {"name:: "MyURL", "path": "../src/MyUrlTypes"} }
// This option enables opting out of emitting es modules artifacts. When set to false, Relay will emit CommonJS modules.
eagerEsModules?: boolean = true
// When set, enum values are imported from a module with this suffix. For example, an enum Foo and this property set to ".test" would be imported from "Foo.test". Note: an empty string is allowed and different from not setting the value, in the example above it would just import from "Foo".
enumModuleSuffix?: string | null
// Directories to ignore under src default: ['**/node_modules/**', '**/__mocks__/**', '**/__generated__/**'],
excludes?: string[] = ["**/node_modules/**", "**/__mocks__/**", "**/__generated__/**"]
// Enable and disable experimental or legacy behaviors. WARNING! These are not stable and may change at any time.
featureFlags?: FeatureFlags | null
// We may generate some content in the artifacts that's stripped in production if __DEV__ variable is set This config option is here to define the name of that special variable
isDevVariableName?: string | null
// Import/export style to use in generated JavaScript modules.
// The desired output language, "flow" or "typescript".
language?: "javascript" | "typescript" | "flow"
// Configuration for @module
moduleImportConfig?: ModuleImportConfig = {
dynamicModuleProvider: null,
operationModuleProvider: null,
surface: null,
} // This option controls whether or not a catch-all entry is added to enum type definitions for values that may be added in the future. Enabling this means you will have to update your application whenever the GraphQL server schema adds new enum values to prevent it from breaking.
noFutureProofEnums?: boolean
// Opt out of source control checks/integration.
noSourceControl?: boolean | null
// When set, generated input types will have the listed fields optional even if the schema defines them as required.
optionalInputFields?: string[] = []
// Query Persist Configuration It contains URL and addition parameters that will be included with the request (think API_KEY, APP_ID, etc...)
persistConfig?: PersistConfig | null
// Whether to treat all JS module names as relative to './' (true) or not. default: true
relativizeJsModulePaths?: boolean = true
// Require all GraphQL scalar types mapping to be defined, will throw if a GraphQL scalar type doesn't have a JS type
requireCustomScalarTypes?: boolean
// Indicates the type to import and use as the context for Relay Resolvers.
resolverContextType?: ResolverContextTypeInput | null
resolversSchemaModule?: ResolversSchemaModuleConfig | null
// Path to schema.graphql
schema?: string
// Extra configuration for the GraphQL schema itself.
schemaConfig?: SchemaConfig = {
connectionInterface: {
cursor: "cursor",
edges: "edges",
endCursor: "endCursor",
hasNextPage: "hasNextPage",
hasPreviousPage: "hasPreviousPage",
node: "node",
pageInfo: "pageInfo",
startCursor: "startCursor",
}, deferStreamInterface: {
deferName: "defer",
ifArg: "if",
initialCountArg: "initialCount",
labelArg: "label",
streamName: "stream",
useCustomizedBatchArg: "useCustomizedBatch",
}, enableTokenField: false,
nodeInterfaceIdField: "id",
nodeInterfaceIdVariableName: "id",
nonNodeIdFields: null,
unselectableDirectiveName: "unselectable",
} // List of directories with schema extensions.
schemaExtensions?: string[] = []
// Root directory of application code
src?: string
// Keep the previous compiler behavior by outputting an union of the raw type and null, and not the **correct** behavior of an union with the raw type, null and undefined.
typescriptExcludeUndefinedFromNullableUnion?: boolean
// Whether to use the `import type` syntax introduced in Typescript version 3.8. This will prevent warnings from `importsNotUsedAsValues`.
useImportTypeSyntax?: boolean