Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 50fcf87

Browse filesBrowse files
captbaritonefacebook-github-bot
captbaritone
authored and
facebook-github-bot
committed
Add page documenting the compiler config (#4985)
Summary: Our compiler config is relatively huge and small details of it change frequently. Keeping it documented and up to date has proved too difficult. However, recently we started driving a JSON schema representation of it and shipping that as part of the VSCode extension to give in-editor feedback about what options exist and to catch errors. However there still has not been an exhaustive place to see what options exist or read about them. This PR attempts to solve that by adding a new documentation page with a hand-written React renderer that traverses the JSON schema and renders a friendly version of it that looks ~like TypeScript types, which should be familiar to our users. Some problems to solve if we want to go this way: - [x] How should we sync the config schema file to the website folder? - [x] How should we automate testing that schema changes do not break this? - I've confirmed that Docusaurus build will fail if we throw in the React components. So, if we are okay with that being our "test" that we can correctly render our config docs, we can just ensure that our react components are defensive and throw on any unhandled cases. - [x] Interlink (and remove duplication) with existing compiler page - [x] See if we can fix anchor links (it scrolls such that the anchor ends up under the header) - [x] Handle dark mode ![localhost_3000_docs_next_getting-started_compiler-config_ (1)](https://github.com/user-attachments/assets/fce7eb4e-bb54-4685-bc73-eb96bbd4109e) Pull Request resolved: #4985 Reviewed By: evanyeung Differential Revision: D74346512 Pulled By: captbaritone fbshipit-source-id: e4443df73bbe01631c7c7b7ec915f81d541d0fc5
1 parent 642f964 commit 50fcf87
Copy full SHA for 50fcf87

9 files changed

+530-7Lines changed: 530 additions & 7 deletions

File tree

Expand file treeCollapse file tree
Open diff view settings
Filter options
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎website/docs/api-reference/relay-runtime/runtime-configuration.md‎

Copy file name to clipboardExpand all lines: website/docs/api-reference/relay-runtime/runtime-configuration.md
+1-1Lines changed: 1 addition & 1 deletion
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ keywords:
1313
If your server's implementation of the Connection Spec differs from the default interface you will need to configure the Relay Runtime to expect the connection type and field names used in your schema. This is done by updating the global ConnectionInterface instance exported by Relay:
1414

1515
:::note
16-
You will also need to update your Relay Compiler Config with these same values.
16+
You will also need to update your [Relay Compiler Config](../../getting-started/compiler-config/#ConnectionInterface) with these same values at the path `schemaConfig.connectionInterface`.
1717
:::
1818

1919
```ts title="/src/ConfigureRelay.ts"
Collapse file

‎website/docs/getting-started/compiler-config.md‎

Copy file name to clipboard
+24Lines changed: 24 additions & 0 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
id: compiler-config
3+
title: Compiler Configuration
4+
slug: /getting-started/compiler-config/
5+
description: Schema description of the Relay Compiler configuration
6+
keywords:
7+
- compiler
8+
- configuration
9+
- config
10+
hide_table_of_contents: false
11+
---
12+
import CompilerConfig from '@site/src/compiler-config/CompilerConfig';
13+
14+
## Compiler Config Options
15+
16+
For information about where the Relay compiler looks for its config file, or a minimal config, see the [Relay Compiler](./compiler.md#Configuration) page.
17+
18+
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.
19+
20+
:::tip
21+
Install the [Relay VSCode extension](../editor-support.md) to get autocomplete, hover tips, and type checking for the options in your Relay config.
22+
:::
23+
24+
<CompilerConfig />
Collapse file

‎website/docs/getting-started/compiler.md‎

Copy file name to clipboardExpand all lines: website/docs/getting-started/compiler.md
+4-3Lines changed: 4 additions & 3 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The Relay compiler will look for a Relay config in the following locations. It's
2121
* `relay.config.(js/mjs/ts)` in your project root
2222
* A `"relay"` key in your `package.json`
2323

24-
The Relay compiler config tells Relay things like where it can find your GraphQL schema and what language your code is writen in. A minimal Relay compiler config looks like this:
24+
The Relay compiler config tells Relay things like where it can find your GraphQL schema and what language your code is written in. A minimal Relay compiler config looks like this:
2525

2626
```json title="relay.config.json"
2727
{
@@ -31,12 +31,13 @@ The Relay compiler config tells Relay things like where it can find your GraphQL
3131
}
3232
```
3333

34-
The compiler config is very powerful, and includes many specialized configuration options. These are not yet exhaustively documented. In the mean time see [relay-compiler-config-schema.json](https://github.com/facebook/relay/blob/main/compiler/crates/relay-compiler/relay-compiler-config-schema.json).
35-
3634
:::tip
3735
Install the [Relay VSCode extension](../editor-support.md) to get autocomplete, hover tips, and type checking for the options in your relay config.
3836
:::
3937

38+
The compiler config is very powerful, and includes many specialized configuration options. For a full enumeration of the available options see the [Compiler Configuration](./compiler-config.md) page.
39+
40+
4041
## Running the compiler
4142

4243
It is generally recommended that you add a `scripts` entry to your `package.json` to make it easy to run the Relay compiler for your project.
Collapse file

‎website/docs/glossary/glossary.md‎

Copy file name to clipboardExpand all lines: website/docs/glossary/glossary.md
+3-3Lines changed: 3 additions & 3 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Compare with [variables](#variables) and see the [relevant section](../guided-to
6363

6464
## Artifact
6565

66-
Files that are generated by the Relay compiler, typically ending in `.graphql.js`.
66+
Files that are generated by the [Relay compiler](../getting-started/compiler.md), typically ending in `.graphql.js`.
6767

6868
<FbInternalOnly>
6969

@@ -91,7 +91,7 @@ A build-time transformation of the Javascript codebase, which turns calls to
9191
graphql`...`
9292
```
9393

94-
into `require(NAME_OF_GENERATED_ARTIFACT)` calls.
94+
into `require(NAME_OF_GENERATED_ARTIFACT)` calls. See [Babel Plugin](../getting-started/babel-plugin.md).
9595

9696
## Client Schema Extension
9797

@@ -135,7 +135,7 @@ In addition, calls to `graphql`...`` are turned into concrete requests at build
135135

136136
## Config
137137

138-
A file or javascript object which controls, among other things, which files are scanned by the Relay [compiler](#compiler) for your project.
138+
A [file or javascript object](../getting-started/compiler-config.md) which controls, among other things, which files are scanned by the Relay [compiler](#compiler) for your project.
139139

140140
## @connection
141141

Collapse file

‎website/docusaurus.config.js‎

Copy file name to clipboardExpand all lines: website/docusaurus.config.js
+2Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -245,6 +245,7 @@ module.exports = {
245245
'./src/css/prism.css',
246246
'./src/css/customTheme.css',
247247
'./src/css/custom.css',
248+
'./src/css/jsonSchema.css',
248249
],
249250
},
250251
gtag: {
@@ -257,6 +258,7 @@ module.exports = {
257258
],
258259
],
259260
plugins: [
261+
require.resolve('./plugins/webpack-alias'),
260262
[
261263
'@docusaurus/plugin-client-redirects',
262264
{
Collapse file

‎website/plugins/webpack-alias.js‎

Copy file name to clipboard
+50Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
/**
2+
* Copyright (c) Meta Platforms, Inc. and affiliates.
3+
*
4+
* This source code is licensed under the MIT license found in the
5+
* LICENSE file in the root directory of this source tree.
6+
*
7+
* @format
8+
* @oncall relay
9+
*/
10+
11+
'use strict';
12+
13+
const fs = require('fs');
14+
const path = require('path');
15+
16+
module.exports = function (context, options) {
17+
return {
18+
name: 'custom-webpack-alias',
19+
configureWebpack() {
20+
// The relative location of the JSON schema file differs between GitHub
21+
// and internal Meta builds, so we need a place to handle that
22+
// conditionality.
23+
24+
const CANDIDATE_PATHS = [
25+
// Used in OSS builds
26+
'../../compiler/crates/relay-compiler/relay-compiler-config-schema.json',
27+
// Used in internal Meta builds
28+
'../../../../../../../../../fbcode/relay/oss/crates/relay-compiler/relay-compiler-config-schema.json',
29+
].map(p => path.resolve(__dirname, p));
30+
31+
const jsonSchemaPath = CANDIDATE_PATHS.find(p => fs.existsSync(p));
32+
33+
if (!jsonSchemaPath) {
34+
throw new Error(
35+
`Could not find JSON schema file for compiler config. Looked in: ${CANDIDATE_PATHS.join(
36+
', ',
37+
)}`,
38+
);
39+
}
40+
41+
return {
42+
resolve: {
43+
alias: {
44+
'@compilerConfigJsonSchema': jsonSchemaPath,
45+
},
46+
},
47+
};
48+
},
49+
};
50+
};
Collapse file

‎website/sidebars.js‎

Copy file name to clipboardExpand all lines: website/sidebars.js
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,7 @@ module.exports = {
158158
'getting-started/quick-start',
159159
'getting-started/babel-plugin',
160160
'getting-started/compiler',
161+
'getting-started/compiler-config',
161162
'editor-support',
162163
'getting-started/production',
163164
],

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.