{"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,"search_vec":"'0.12.4':46 'annot':68,95 'apollo':76 'applic':43 'approach':59 'base':58 'bind':10 'build':5 'close':80 'compil':3,17,30 'current':44 'custom':93 'deep':87 'default':22 'differenti':71 'ecosystem':84 'enabl':35 'experiment':48 'extract':61 'file':67 'flow':23 'generat':8,25 'gql':70 'graph':89 'graphql':12,39,62 'hierarch':88 'integr':79 'javascript':96 'like':75 'nativ':33 'oper':63 'queri':18,40 'regex':57 'regex-bas':56 'relay':2,16,29,51,83 'relay-compil':15,28 'replac':20 'safe':38 'scala':1,65 'scala.js':9,32,42,77 'scalaj':94 'schema':13 'similar':73 'sourc':66 'specif':52 'spread':91 'structur':90 'support':50,86 'tool':6,74 'trait':34 'type':24,37 'type-saf':36 'use':54 'version':45","created_at":"2026-05-01T17:45:56.714488+00:00","updated_at":"2026-05-01T17:45:56.714488+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/dispalt/relay-modern-helper","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/scala-relay-compiler","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-05-01","next_check":"2026-07-30","install_tag":null}}