relay-compiler

What is relay-compiler?

The relay-compiler npm package is a tool used in the Relay framework to compile GraphQL queries into efficient runtime artifacts. It helps in optimizing and validating GraphQL queries, ensuring that they are compatible with the schema and generating the necessary code to fetch data efficiently.

What are relay-compiler's main functionalities?

Compiling GraphQL Queries

This feature allows you to compile GraphQL queries defined in your project against a given schema. The code sample demonstrates how to use the compile function from relay-compiler to compile queries and handle the result.

const { compile } = require('relay-compiler');

const schema = 'path/to/schema.graphql';
const documents = 'path/to/documents.graphql';

compile({
  schema,
  documents,
  src: 'src',
  extensions: ['js', 'jsx'],
  verbose: true
}).then(() => {
  console.log('Compilation successful');
}).catch(error => {
  console.error('Compilation failed', error);
});

Generating Artifacts

This feature generates runtime artifacts from the compiled GraphQL queries. The code sample shows how to use the generate function to create these artifacts, which are essential for efficient data fetching in a Relay application.

const { generate } = require('relay-compiler');

const schema = 'path/to/schema.graphql';
const documents = 'path/to/documents.graphql';

generate({
  schema,
  documents,
  src: 'src',
  extensions: ['js', 'jsx'],
  verbose: true
}).then(() => {
  console.log('Artifacts generated successfully');
}).catch(error => {
  console.error('Artifact generation failed', error);
});

Schema Validation

This feature validates the GraphQL schema against the queries defined in your project. The code sample demonstrates how to use the validate function to ensure that your queries are compatible with the schema.

const { validate } = require('relay-compiler');

const schema = 'path/to/schema.graphql';
const documents = 'path/to/documents.graphql';

validate({
  schema,
  documents,
  src: 'src',
  extensions: ['js', 'jsx'],
  verbose: true
}).then(() => {
  console.log('Schema validation successful');
}).catch(error => {
  console.error('Schema validation failed', error);
});

Other packages similar to relay-compiler

graphql-code-generator

GraphQL Code Generator is a tool that generates code out of your GraphQL schema and operations. It supports various languages and frameworks, providing a flexible and extensible way to generate type-safe code. Compared to relay-compiler, it offers broader support for different environments and more customization options.

apollo-codegen

Apollo Codegen is a tool for generating static types for GraphQL queries in TypeScript and Flow. It is part of the Apollo ecosystem and is designed to work seamlessly with Apollo Client. While relay-compiler is specific to the Relay framework, Apollo Codegen is tailored for use with Apollo Client, making it a better fit for projects using Apollo.

graphql-cli

GraphQL CLI is a command-line tool that provides various utilities for working with GraphQL, including schema validation, query validation, and code generation. It is more general-purpose compared to relay-compiler and can be used with different GraphQL clients and servers.

README

Relay Compiler

Relay-Compiler is a code-generation toolkit for GraphQL. It contains the core functionalities of GraphQL code-gen, including file parsing, validation, syntax tree parsing and transformation.

Configuration in package.json

The simplest way to configure relay is to add a new relay section to your package.json that contains the relay config.

At minimum, the relay config must specify where to find source files (i.e. files containing graphql literals) and the GraphQL schema for the project.

// adding new section to package json
{
  ...
 "scripts": {
    "relay": "relay-compiler"
 },
 ...
 // relay configuration
 "relay": {
    "src": "./src",
    "schema": "./src/schema/app_schema.graphql"
  }
}

Relay Compiler will automatically discover the config if:

• There is a relay.config.json, relay.config.js file at the root of the project (i.e. in the same folder as the package.json file).
• The package.json file contains a "relay" key.

Alternatively, the path to a configuration file can be specified as an argument:

npm run relay ./relay.json

or with yarn

yarn relay ./relay.json

Please note, in this case you'll need to provide a separate configuration for the babel plugin.

File Finder

Relay compiler uses watchman to find file sources, and "listen" to the file changes in the "watch" mode. If watchman is not available, the compiler will use glob to query the filesystem for files.

Configuration

Supported compiler configuration options

• src Root directory of application code. [string] [required]

• schema Relative path to the file with GraphQL SDL file. [string] [required]

• language The name of the language used for input files and generated artifacts. ["javascript" | "typescript" | "flow"] [required].

• artifactDirectory A specific directory to output all artifacts to. When enabling this the babel plugin needs artifactDirectory to be set as well. [string]

• excludes Directories to ignore under src. [array] [default: ["/node_modules/", "/mocks/", "/generated/"]]

• schemaExtensions List of directories with schema extensions. [array]

• schemaConfig

  • nodeInterfaceIdField Configure the name of the globally unique ID field on the Node interface. Useful if you can't use the default id field name.
  • nodeInterfaceIdVariableName Specifies the name of the variable expected by the node query to pass the Node id. [string][default: "id"]
  • nonNodeIdFields Restricts the type of all fields named id to ID.
    • allowedIdTypes Mappings from types in your schema to allowed types for their fields named id (e.g. "ObjectType": "CustomIdType"). [object]

• noFutureProofEnums This option controls whether or not a catch-all entry is added to enum type definitions 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. [boolean][default: false]

• customScalars Mappings from custom scalars in your schema to built-in GraphQL types, for type emission purposes. [object]

• eagerEsModules This option enables emitting ES modules artifacts. [boolean][default: false]

• persistConfig Relay supports two versions of the config:

• • Remote Persisting:

  • url String, URL to send a POST request to to persist. This field is required in persistConfig [string]

  • params The document will be in a POST parameter text. This map can contain additional parameters to send. [object]

  • concurrency The maximum number concurrent requests that will be made to url. Use a value greater than 0. [number]

• • Local Persisting:
  • file Path for the JSON file that will contain operations map. Compiler will write queries in the format: { "md5(queryText) => "queryText", ...}. [string]

• codegenCommand Command name that for relay compiler. [string]

• isDevVariableName Name of the global variable for dev mode (__DEV__). [string]

• jsModuleFormat Formatting style for generated files. commonjs or haste. Default is commonjs. [string]

• diagnosticReportConfig Options for configuring the output of compiler diagnostics. [object]

  • criticalLevel The severity level of diagnostics that will cause the compiler to error out on. ["error" | "warning" | "info"]

CLI Arguments

• --repersist Run the persister even if the query has not changed.
• --watch Run compiler in watch mode. Requires watchman to be installed.
• --output Output format of the compiler. Supported options: debug | verbose | quiet | quietWithErrors. The default value is verbose.
• --validate Looks for pending changes and exits with non-zero code instead of writing to disk.