{"id":27375,"library":"scala-relay-compiler","title":"Scala Relay Compiler","description":"A build tool that generates Scala.js bindings from GraphQL schemas and Relay-compiled queries. It replaces the default Flow type generation of the relay-compiler with Scala.js native traits, enabling type-safe GraphQL queries in Scala.js applications. Current version 0.12.4 is experimental and supports Relay specifications. It uses a regex-based approach to extract GraphQL operations from Scala source files annotated with @gql. Differentiating from similar tools like Apollo Scala.js, it integrates closely with the Relay ecosystem and supports deep hierarchical graph structures, spreading, and custom scalajs annotations.","status":"active","version":"0.12.4","language":"javascript","source_language":"en","source_url":"https://github.com/dispalt/relay-modern-helper","tags":["javascript"],"install":[{"cmd":"npm install scala-relay-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add scala-relay-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add scala-relay-compiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"scala-relay-compiler generates Scala.js bindings from the output of the relay-compiler","package":"relay-compiler","optional":false},{"reason":"Runtime dependency for the generated Scala.js code","package":"scala-js","optional":false}],"imports":[{"note":"scala-relay-compiler is installed via npm and used as a CLI tool, not imported as a JavaScript module.","wrong":"N/A","symbol":"scala-relay-compiler","correct":"npm install scala-relay-compiler"},{"note":"This is a Scala.js import used in generated code to define query objects.","wrong":"import scala.scalajs.js.JSON.parse","symbol":"relay.graphql.GenericGraphQLTaggedNode","correct":"import relay.graphql.GenericGraphQLTaggedNode"},{"note":"The @gql annotation is a string-based annotation in Scala source files, not a template literal.","wrong":"val gql = graphql`...`","symbol":"@gql","correct":"@gql(\"\"\"...\"\"\")"}],"quickstart":{"code":"// 1. Install relay-compiler and scala-relay-compiler\nnpm install --save-dev relay-compiler scala-relay-compiler\n\n// 2. Create a GraphQL schema file (schema.graphql)\n// 3. Create Scala source files with @gql annotations\n// Example: src/main/scala/com/example/Foo.scala\npackage com.example\n\nobject Foo {\n  val query = @gql(\"\"\"\n  query ExampleQuery {\n    dictionary {\n      ...DictionaryComponent_word\n    }\n  }\n  \"\"\")\n\n  val fragment = @gql(\"\"\"\n  fragment DictionaryComponent_word on Word {\n    id\n    text\n  }\n  \"\"\")\n}\n\n// 4. Run relay-compiler to generate JSON artifacts\nnpx relay-compiler --schema schema.graphql --src src/ --language javascript --artifactDirectory relay-artifacts/\n\n// 5. Run scala-relay-compiler to generate Scala.js bindings\nnpx scala-relay-compiler --src src/ --schema schema.graphql --out target/generated/\n\n// 6. Include generated files in your Scala.js project build","lang":"javascript","description":"Complete workflow to set up scala-relay-compiler with a GraphQL schema and Scala source files."},"warnings":[{"fix":"Ensure @gql(\"\"\"...\"\"\") is exactly as specified; do not use string interpolation or concatenation inside @gql.","message":"The @gql annotation uses a regex-based extraction, not a compile-time macro. If the string formatting is off (e.g., missing triple quotes), the query may not be found.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Pin relay-compiler version to match the scala-relay-compiler's expected version (e.g., relay-compiler 1.6.2 for scala-relay-compiler 0.11.0).","message":"scala-relay-compiler relies on the relay-compiler's JSON output for query artifacts. Changes to relay-compiler output format (e.g., version bumps) may break generation.","severity":"gotcha","affected_versions":">=0.11.0"},{"fix":"Check the changelog and README for version compatibility before upgrading.","message":"scala-relay-compiler is experimental and may have breaking changes between minor versions. Version 0.12.4 may not be compatible with relay-compiler versions >1.6.2.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Ensure your project is configured for Scala.js (e.g., sbt-scalajs plugin) and includes the relay runtime library.","message":"The generated Scala.js code uses js.native traits and may require Scala.js runtime setup.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Verify that the @gql annotation is exactly `@gql(\"\"\"...\"\"\")` with no extra whitespace or newlines between `@gql` and the opening quote.","cause":"The regex-based extraction fails to detect the fragment due to incorrect quoting or spacing around the @gql annotation.","error":"fragment DictionaryComponent_definition is not used"},{"fix":"Run `npm install --save-dev relay-compiler`.","cause":"relay-compiler is not installed as a dependency.","error":"Error: Cannot find module 'relay-compiler'"},{"fix":"Ensure the code is compiled with Scala.js and the resulting JavaScript is run in a browser or Node.js environment with the Scala.js runtime loaded.","cause":"Running the generated Scala.js code in a JavaScript environment without the Scala.js runtime.","error":"TypeError: scala.scalajs.js.JSON.parse is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}