0
# Configuration
1

2
The Relay Compiler uses a flexible JSON-based configuration system that supports both single-project and multi-project setups with extensive customization options.
3

4
## Configuration File Discovery
5

6
The compiler searches for configuration in this order:
7

8
1. `--config` command-line option
9
2. `relay.config.json` in current directory
10
3. `relay.config.js` in current directory
11
4. `relay` key in `package.json`
12
5. Walk up directory tree repeating the search
13

14
## Single Project Configuration
15

16
For projects with a single GraphQL schema and source directory.
17

18
```typescript
19
{ .api }
20
interface SingleProjectConfigFile {
21
  // Required
22
  language: "javascript" | "typescript" | "flow";
23
  
24
  // Core paths
25
  src?: string;                    // Root source directory (default: "")
26
  schema?: string;                 // Path to schema.graphql (default: "")
27
  artifactDirectory?: string;      // Specific output directory
28
  
29
  // File handling
30
  excludes?: string[];             // File patterns to ignore
31
  schemaExtensions?: string[];     // Directories with schema extensions
32
  
33
  // JavaScript/TypeScript specific
34
  customScalarTypes?: Record<string, string>;  // GraphQL scalar to JS type mappings
35
  jsModuleFormat?: "commonjs" | "haste";       // Module format
36
  eagerEsModules?: boolean;                    // Enable ES modules (default: true)
37
  
38
  // Advanced options
39
  persistConfig?: PersistConfig;               // Query persistence
40
  featureFlags?: FeatureFlags;                 // Experimental features
41
  moduleImportConfig?: ModuleImportConfig;     // @module directive config
42
  schemaConfig?: SchemaConfig;                 // Schema interface config
43
}
44
```
45

46
### Basic Single Project Example
47

48
```json
49
{
50
  "language": "typescript",
51
  "src": "./src",
52
  "schema": "./schema.graphql",
53
  "artifactDirectory": "./src/__generated__",
54
  "excludes": ["**/node_modules/**", "**/__mocks__/**"]
55
}
56
```
57

58
## Multi Project Configuration
59

60
For monorepos or projects with multiple GraphQL schemas.
61

62
```typescript
63
{ .api }
64
interface MultiProjectConfigFile {
65
  // Required
66
  sources: Record<string, string>;           // Path-to-project mapping
67
  projects: Record<string, ProjectConfig>;   // Project configurations
68
  
69
  // Global options
70
  excludes?: string[];                       // Global exclusion patterns
71
  featureFlags?: FeatureFlags;               // Global feature flags
72
  generatedSources?: string[];               // Generated file directories
73
  savedStateConfig?: SavedStateConfig;       // Watchman saved state
74
}
75
```
76

77
### Multi Project Example
78

79
```json
80
{
81
  "sources": {
82
    "./apps/web/src": "web",
83
    "./apps/mobile/src": "mobile",
84
    "./packages/shared/src": "shared"
85
  },
86
  "projects": {
87
    "web": {
88
      "language": "typescript",
89
      "schema": "./apps/web/schema.graphql",
90
      "artifactDirectory": "./apps/web/src/__generated__"
91
    },
92
    "mobile": {
93
      "language": "typescript", 
94
      "schema": "./apps/mobile/schema.graphql",
95
      "artifactDirectory": "./apps/mobile/src/__generated__"
96
    }
97
  }
98
}
99
```
100

101
## Project Configuration
102

103
Individual project settings within multi-project configurations.
104

105
```typescript
106
{ .api }
107
interface ProjectConfig {
108
  // Core settings
109
  language: "javascript" | "typescript" | "flow";
110
  schema: string;                              // Schema file path
111
  artifactDirectory?: string;                  // Output directory
112
  
113
  // File handling
114
  excludes?: string[];                         // Project-specific excludes
115
  schemaExtensions?: string[];                 // Schema extension directories
116
  
117
  // Code generation
118
  customScalarTypes?: Record<string, string>;  // Scalar type mappings
119
  jsModuleFormat?: "commonjs" | "haste";       // Module format
120
  eagerEsModules?: boolean;                    // ES modules support
121
  
122
  // Advanced features
123
  persistConfig?: PersistConfig;               // Persistence configuration
124
  featureFlags?: FeatureFlags;                 // Feature flags override
125
}
126
```
127

128
## Persistence Configuration
129

130
Configure how GraphQL queries are persisted for production optimization.
131

132
### Remote Persistence
133

134
```typescript
135
{ .api }
136
interface RemotePersistConfig {
137
  url: string;                    // Persistence endpoint URL
138
  headers?: Record<string, string>; // Additional HTTP headers
139
  params?: Record<string, string>;  // Additional POST parameters
140
  concurrency?: number;            // Request concurrency limit
141
  includeQueryText?: boolean;      // Include query text in response
142
}
143
```
144

145
**Example:**
146
```json
147
{
148
  "persistConfig": {
149
    "url": "https://api.example.com/persist-query",
150
    "headers": {
151
      "Authorization": "Bearer token",
152
      "Content-Type": "application/json"
153
    },
154
    "concurrency": 10,
155
    "includeQueryText": false
156
  }
157
}
158
```
159

160
### Local Persistence
161

162
```typescript
163
{ .api }
164
interface LocalPersistConfig {
165
  file: string;                          // Output file path
166
  algorithm?: "MD5" | "SHA1" | "SHA256"; // Hash algorithm (default: MD5)
167
  include_query_text?: boolean;          // Include query in output
168
}
169
```
170

171
**Example:**
172
```json
173
{
174
  "persistConfig": {
175
    "file": "./persisted-queries.json",
176
    "algorithm": "SHA256",
177
    "include_query_text": true
178
  }
179
}
180
```
181

182
## Feature Flags
183

184
Enable experimental and advanced compiler features.
185

186
```typescript
187
{ .api }
188
interface FeatureFlags {
189
  // Each flag can be: disabled | enabled | { "limited": string[] } | { "rollout": number }
190
  [flagName: string]: 
191
    | "disabled" 
192
    | "enabled" 
193
    | { limited: string[] }     // Allowlist of files/projects
194
    | { rollout: number };      // Percentage rollout (0-100)
195
}
196
```
197

198
### Key Feature Flags
199

200
```typescript
201
{ .api }
202
interface KeyFeatureFlags {
203
  // Core features
204
  actor_change_support?: FeatureFlagValue;              // Actor change feature
205
  allow_output_type_resolvers?: FeatureFlagValue;       // Output type resolvers
206
  compact_query_text?: FeatureFlagValue;                // Compact query printing
207
  
208
  // Fragment features  
209
  enable_fragment_argument_transform?: FeatureFlagValue; // Fragment arguments
210
  enable_relay_resolver_mutations?: FeatureFlagValue;    // Resolver mutations
211
  
212
  // Generation features
213
  text_artifacts?: FeatureFlagValue;                     // Text artifact generation
214
  generate_typescript?: FeatureFlagValue;                // TypeScript generation
215
  
216
  // Performance features
217
  skip_redundant_nodes?: FeatureFlagValue;               // Skip redundant AST nodes
218
  enable_parallelization?: FeatureFlagValue;             // Parallel compilation
219
}
220
```
221

222
### Feature Flag Examples
223

224
```json
225
{
226
  "featureFlags": {
227
    "actor_change_support": "enabled",
228
    "compact_query_text": "disabled",
229
    "enable_fragment_argument_transform": {
230
      "rollout": 50
231
    },
232
    "generate_typescript": {
233
      "limited": ["web", "admin"]
234
    }
235
  }
236
}
237
```
238

239
## Module Import Configuration
240

241
Configure @module directive behavior for component imports.
242

243
```typescript
244
{ .api }
245
interface ModuleImportConfig {
246
  dynamicModuleProvider?: string;    // Dynamic import provider function
247
}
248
```
249

250
**Example:**
251
```json
252
{
253
  "moduleImportConfig": {
254
    "dynamicModuleProvider": "./src/utils/dynamicImport.js"
255
  }
256
}
257
```
258

259
## Schema Configuration
260

261
Configure GraphQL schema interface handling.
262

263
```typescript
264
{ .api }
265
interface SchemaConfig {
266
  nodeInterfaceIdField?: string;           // Node interface ID field name
267
  nodeInterfaceIdType?: string;            // Node interface ID type
268
  connectionInterface?: {                  // Connection interface config
269
    connectionField?: string;
270
    edgesField?: string;
271
    nodeField?: string;
272
  };
273
}
274
```
275

276
**Example:**
277
```json
278
{
279
  "schemaConfig": {
280
    "nodeInterfaceIdField": "id",
281
    "nodeInterfaceIdType": "ID!",
282
    "connectionInterface": {
283
      "connectionField": "connection",
284
      "edgesField": "edges", 
285
      "nodeField": "node"
286
    }
287
  }
288
}
289
```
290

291
## Saved State Configuration
292

293
Configure Watchman saved state for faster incremental builds.
294

295
```typescript
296
{ .api }
297
interface SavedStateConfig {
298
  filename?: string;        // Saved state file path
299
  config?: string;         // Watchman config name
300
}
301
```
302

303
**Example:**
304
```json
305
{
306
  "savedStateConfig": {
307
    "filename": ".watchman-state",
308
    "config": "relay-compiler"
309
  }
310
}
311
```
312

313
## CLI Configuration Override
314

315
Override configuration via command-line options:
316

317
```typescript
318
{ .api }
319
interface CLIConfig {
320
  src?: string;                    // Override source directory
321
  schema?: string;                 // Override schema path
322
  artifact_directory?: string;     // Override output directory
323
}
324
```
325

326
These CLI options take precedence over file-based configuration.
327

328
## Configuration Validation
329

330
The compiler validates configuration files against a JSON schema. Get the schema:
331

332
```bash
333
relay-compiler config-json-schema > relay.schema.json
334
```
335

336
### Common Validation Errors
337

338
```typescript
339
{ .api }
340
interface ConfigValidationErrors {
341
  "Missing required field": string;     // Required field not provided
342
  "Invalid language": string;           // Unsupported language option
343
  "Schema file not found": string;      // Schema path doesn't exist
344
  "Invalid feature flag": string;       // Unknown feature flag
345
  "Circular dependency": string;        // Circular project dependencies
346
}
347
```
348

349
## Environment-Specific Configuration
350

351
```json
352
{
353
  "language": "typescript",
354
  "src": "./src",
355
  "schema": "./schema.graphql",
356
  "featureFlags": {
357
    "enable_experimental_features": {
358
      "limited": ["development", "staging"]
359
    }
360
  },
361
  "persistConfig": {
362
    "url": "${PERSIST_ENDPOINT}",
363
    "headers": {
364
      "Authorization": "Bearer ${API_TOKEN}"
365
    }
366
  }
367
}
368
```
369

370
Note: Environment variable substitution depends on your build process - the compiler itself doesn't perform substitution.