{"id":11932,"library":"relay-compiler-language-typescript","title":"Relay Compiler TypeScript Language Plugin","description":"This package served as a language plugin for `relay-compiler`, providing TypeScript support, including the emission of type definitions for Relay artifacts. It enabled Relay users to leverage TypeScript for their GraphQL operations and component props. The current stable version is 15.0.1. Historically, it filled a critical gap by adding TypeScript capabilities to Relay's build process. However, as of Relay v13, TypeScript support is natively integrated into the core `relay-compiler`, rendering this standalone plugin obsolete. Its release cadence was tied to major Relay versions and bug fixes, but active development has ceased due to its superseded status. Developers are now advised to use the built-in TypeScript features of `relay-compiler` directly.","status":"deprecated","version":"15.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/relay-tools/relay-compiler-language-typescript","tags":["javascript","graphql","react","relay","typescript"],"install":[{"cmd":"npm install relay-compiler-language-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add relay-compiler-language-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add relay-compiler-language-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for TypeScript types related to Relay's React integration.","package":"@types/react-relay","optional":false},{"reason":"Peer dependency for TypeScript types related to Relay's runtime APIs.","package":"@types/relay-runtime","optional":false},{"reason":"The core Relay compiler that this package plugs into to provide TypeScript language support.","package":"relay-compiler","optional":false},{"reason":"Relay's core runtime library, required for the generated code and types.","package":"relay-runtime","optional":false},{"reason":"Required for its TypeScript compilation and type generation capabilities.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"import * as RelayTS from 'relay-compiler-language-typescript';","symbol":"Relay Compiler Configuration","correct":"relay-compiler --language typescript --src ./src --schema data/schema.graphql --artifactDirectory ./src/__generated__"},{"note":"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.","wrong":"import { MyComponent_data$key } from 'relay-compiler-language-typescript';","symbol":"TypeScript Type Artifacts","correct":"import { MyComponent_data$key } from './__generated__/MyComponent_data.graphql';"},{"note":"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.","wrong":"import { addBanner } from 'relay-compiler-language-typescript'","symbol":"Custom Headers (banner option)","correct":"{ \"compilerOptions\": { \"banner\": \"/* © 2021 Example.org - @generated code */\" } }"}],"quickstart":{"code":"{\n  \"devDependencies\": {\n    \"graphql\": \"^15.7.0\",\n    \"relay-compiler\": \">=12.0.0\",\n    \"typescript\": \">=4.5.0\",\n    \"relay-compiler-language-typescript\": \"^15.0.0\"\n  },\n  \"scripts\": {\n    \"relay\": \"relay-compiler --src ./src --schema data/schema.graphql --language typescript --artifactDirectory ./src/__generated__\"\n  }\n}\n\n// tsconfig.json\n{\n  \"compilerOptions\": {\n    \"module\": \"ES2015\",\n    \"target\": \"ES2020\"\n  }\n}\n\n// .babelrc\n{\n  \"plugins\": [[\"relay\", { \"artifactDirectory\": \"./src/__generated__\" }]]\n}","lang":"json","description":"Demonstrates the `package.json` setup for installing the plugin and `relay-compiler`, configuring the `relay` script, and essential `tsconfig.json` and `.babelrc` settings."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=15.0.1"},{"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.","message":"`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.","severity":"breaking","affected_versions":">=15.0.0"},{"fix":"Upgrade your project's `typescript` peer dependency to version 4.x or higher before upgrading to `relay-compiler-language-typescript` v14.0.0.","message":"`relay-compiler-language-typescript` v14.0.0 dropped support for TypeScript 3.","severity":"breaking","affected_versions":">=14.0.0"},{"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.","message":"Improper `tsconfig.json` module settings can prevent `babel-plugin-relay` from finding `graphql` function usages, leading to compilation failures.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The TypeScript compiler (`tsc`) generated CommonJS-style imports and namespaces the `graphql` function, making it unidentifiable by `babel-plugin-relay`.","error":"babel-plugin-relay cannot find the locations where the `graphql` function is being used (e.g., 'react_relay_1.graphql')."},{"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.","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.","error":"Unexpected module loading errors or type conflicts in the browser during development with React Hot Loader (RHL)."},{"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`).","cause":"Your project's `typescript` version is older than the minimum required by `relay-compiler-language-typescript` v15 and above.","error":"Error: `relay-compiler-language-typescript` requires `typescript@>=4.5.0` to be installed."}],"ecosystem":"npm"}