Scala Relay Compiler

0.12.4 verified Fri May 01 auth: no javascript

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.

Common errors

error fragment DictionaryComponent_definition is not used ↓

cause The regex-based extraction fails to detect the fragment due to incorrect quoting or spacing around the @gql annotation.

fix

Verify that the @gql annotation is exactly @gql("""...""") with no extra whitespace or newlines between @gql and the opening quote.

error Error: Cannot find module 'relay-compiler' ↓

cause relay-compiler is not installed as a dependency.

fix

Run npm install --save-dev relay-compiler.

error TypeError: scala.scalajs.js.JSON.parse is not a function ↓

cause Running the generated Scala.js code in a JavaScript environment without the Scala.js runtime.

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.

Warnings

gotcha 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. ↓

fix Ensure @gql("""...""") is exactly as specified; do not use string interpolation or concatenation inside @gql.

gotcha 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. ↓

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).

breaking 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. ↓

fix Check the changelog and README for version compatibility before upgrading.

gotcha The generated Scala.js code uses js.native traits and may require Scala.js runtime setup. ↓

fix Ensure your project is configured for Scala.js (e.g., sbt-scalajs plugin) and includes the relay runtime library.

Install

npm install scala-relay-compiler

yarn add scala-relay-compiler

pnpm add scala-relay-compiler

Imports

scala-relay-compiler
wrong
```
N/A
```
correct
```
npm install scala-relay-compiler
```
scala-relay-compiler is installed via npm and used as a CLI tool, not imported as a JavaScript module.
relay.graphql.GenericGraphQLTaggedNode
wrong
```
import scala.scalajs.js.JSON.parse
```
correct
```
import relay.graphql.GenericGraphQLTaggedNode
```
This is a Scala.js import used in generated code to define query objects.
@gql
wrong
```
val gql = graphql`...`
```
correct
```
@gql("""...""")
```
The @gql annotation is a string-based annotation in Scala source files, not a template literal.

Quickstart

Complete workflow to set up scala-relay-compiler with a GraphQL schema and Scala source files.

// 1. Install relay-compiler and scala-relay-compiler
npm install --save-dev relay-compiler scala-relay-compiler

// 2. Create a GraphQL schema file (schema.graphql)
// 3. Create Scala source files with @gql annotations
// Example: src/main/scala/com/example/Foo.scala
package com.example

object Foo {
  val query = @gql("""
  query ExampleQuery {
    dictionary {
      ...DictionaryComponent_word
    }
  }
  """)

  val fragment = @gql("""
  fragment DictionaryComponent_word on Word {
    id
    text
  }
  """)
}

// 4. Run relay-compiler to generate JSON artifacts
npx relay-compiler --schema schema.graphql --src src/ --language javascript --artifactDirectory relay-artifacts/

// 5. Run scala-relay-compiler to generate Scala.js bindings
npx scala-relay-compiler --src src/ --schema schema.graphql --out target/generated/

// 6. Include generated files in your Scala.js project build