Relay Compiler TypeScript Language Plugin

Common errors

• babel-plugin-relay cannot find the locations where the `graphql` function is being used (e.g., 'react_relay_1.graphql').

  cause The TypeScript compiler (`tsc`) generated CommonJS-style imports and namespaces the `graphql` function, making it unidentifiable by `babel-plugin-relay`.
  fix In your `tsconfig.json`, set `compilerOptions.module` to `ES2015` or higher, and `compilerOptions.target` to `ES2020` or a compatible modern target. This ensures `tsc` outputs ES module syntax that `babel-plugin-relay` can correctly parse.

• Unexpected module loading errors or type conflicts in the browser during development with React Hot Loader (RHL).

  cause React Hot Loader's module replacement mechanism can struggle with dynamically generated TypeScript type definition files, leading to runtime errors or incorrect hot module updates.
  fix This package has known incompatibilities with RHL. The recommended solution is to transition to `react-refresh` (used in tools like Create React App v4+), which offers more robust hot reloading capabilities for modern React applications. Alternatively, configure RHL to exclude Relay-generated artifact directories from its processing.

• Error: `relay-compiler-language-typescript` requires `typescript@>=4.5.0` to be installed.

  cause Your project's `typescript` version is older than the minimum required by `relay-compiler-language-typescript` v15 and above.
  fix Update your project's `typescript` dependency to `^4.5.0` or a newer compatible version (e.g., `npm install typescript@^4.5.0` or `yarn add typescript@^4.5.0`).

Warnings

• breaking This package is explicitly marked as obsolete. Relay version 13.0.0 and later now include native TypeScript support directly within the `relay-compiler`. Continued use of `relay-compiler-language-typescript` is discouraged.
  Fix: Upgrade to `relay-compiler` v13.0.0 or higher and remove `relay-compiler-language-typescript` from your dependencies. Update your `relay-compiler` configuration to use the native TypeScript support.
• breaking `relay-compiler-language-typescript` v15.0.0 introduced breaking changes related to TypeScript 4.5 type generation, and requires a minimum TypeScript version of 4.5.0.
  Fix: Ensure your project's `typescript` peer dependency is at version 4.5.0 or higher. Review generated types for any subtle changes in behavior or stricter enforcement.
• breaking `relay-compiler-language-typescript` v14.0.0 dropped support for TypeScript 3.
  Fix: Upgrade your project's `typescript` peer dependency to version 4.x or higher before upgrading to `relay-compiler-language-typescript` v14.0.0.
• gotcha Improper `tsconfig.json` module settings can prevent `babel-plugin-relay` from finding `graphql` function usages, leading to compilation failures.
  Fix: Always set `compilerOptions.module` to `ES2015` (or higher) and `compilerOptions.target` to `ES2020` (or the highest compatible with your Babel setup) in your `tsconfig.json` to ensure `tsc` generates compatible ES module syntax.
• gotcha React Hot Loader (RHL) is known to have compatibility issues with generated code, including Relay's typing artifacts, which can cause module loading errors in the browser during hot reloading.
  Fix: The project maintainers state that `relay-compiler-language-typescript` cannot guarantee compatibility with RHL. Consider migrating to more modern hot-reloading solutions like React Refresh, or disabling RHL for files containing Relay artifacts.

Install

• npm install relay-compiler-language-typescript npm
• yarn add relay-compiler-language-typescript yarn
• pnpm add relay-compiler-language-typescript pnpm

Imports

• Relay Compiler Configuration
  wrong:

  import * as RelayTS from 'relay-compiler-language-typescript';

  correct:

  relay-compiler --language typescript --src ./src --schema data/schema.graphql --artifactDirectory ./src/__generated__

  This package functions as a plugin for `relay-compiler`. It is enabled by specifying `--language typescript` in the `relay-compiler` CLI arguments or `relay.config.json`, rather than through direct programmatic imports in application code. As of Relay v13+, this explicit configuration is no longer necessary as TypeScript support is built-in.
• TypeScript Type Artifacts
  wrong:

  import { MyComponent_data$key } from 'relay-compiler-language-typescript';

  correct:

  import { MyComponent_data$key } from './__generated__/MyComponent_data.graphql';

  The primary output of this plugin (and now native Relay TS support) is TypeScript type definitions for Relay artifacts. These types are generated into specified directories (e.g., `__generated__`) and then imported from those *generated* files into your application code, not directly from the `relay-compiler-language-typescript` package itself.
• Custom Headers (banner option)
  wrong:

  import { addBanner } from 'relay-compiler-language-typescript'

  correct:

  { "compilerOptions": { "banner": "/* © 2021 Example.org - @generated code */" } }

  The `banner` option for custom headers is a configuration setting passed to `relay-compiler` (typically in `relay.config.json` within the `compilerOptions` block), not a function or object imported directly from the package into application code.

Quickstart

Demonstrates the `package.json` setup for installing the plugin and `relay-compiler`, configuring the `relay` script, and essential `tsconfig.json` and `.babelrc` settings.

{
  "devDependencies": {
    "graphql": "^15.7.0",
    "relay-compiler": ">=12.0.0",
    "typescript": ">=4.5.0",
    "relay-compiler-language-typescript": "^15.0.0"
  },
  "scripts": {
    "relay": "relay-compiler --src ./src --schema data/schema.graphql --language typescript --artifactDirectory ./src/__generated__"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "module": "ES2015",
    "target": "ES2020"
  }
}

// .babelrc
{
  "plugins": [["relay", { "artifactDirectory": "./src/__generated__" }]]
}