scalajs-graphql

scalajs-graphql provides GraphQL clients and utilities, in a type-safe manner, for Scala.js.

Disclaimer: scalajs-graphql has not been released and is under heavy development at the moment. You could still publish locally to use it, but keep in mind that something may not work as expected. We are working to release the very first version soon.

Features

• GraphQL clients
  • Apollo
  • Relay
• UI framework integrations
  • React (with scalajs-react)
  • Maybe more
• Scala code generation (generating case classes, traits, etc.)
  • Schema
  • Operations (queries, mutations, subscriptions)
  • Fragments
  • Input types
• Server-side rendering
• Testing utilities

Installation

As scalajs-graphql is not released yet, you have to build locally to use it.

$ git clone https://github.com/ngthanhtrung/scalajs-graphql.git
$ cd scalajs-graphql
$ sbt publishLocal

Add this to your project/plugins.sbt file:

addSbtPlugin("com.ngthanhtrung" % "sbt-graphql-codegen" % "0.1.0-SNAPSHOT")

You can then configure where scalajs-graphql puts generated GraphQL classes in your project settings in build.sbt:

graphqlCodegenPackage := Some("com.example")

Usage

Say you have this schema definition in src/main/resources/schema.graphql:

type Name {
  firstName: String!
  lastName: String
}

enum Gender {
  MALE
  FEMALE
  UNKNOWN
}

type Person {
  name: Name!
  gender: Gender!
  age: Int
}

type Query {
  peopleByGender(gender: Gender!): [Person]
}

schema {
  query: Query
}

You can write your own query in src/main/resources/people-by-gender-query.graphql like this:

query PeopleByGender($gender: Gender!) {
  peopleByGender(gender: $gender) {
    name {
      firstName
      lastName
    }
    gender
    age
  }
}

scalajs-graphql will automatically generate your query structure in Scala:

package com.example

// Some parts are omitted for brevity

sealed abstract class Gender

object Gender {
  case object MALE extends Gender
  case object FEMALE extends Gender
  case object UNKNOWN extends Gender
}

// Note that "Query" suffix is added to your query name
object PeopleByGenderQuery {

  final case class Variables(gender: Gender)

  type Props = ApolloQueryProps[Data]

  final case class Data(
    peopleByGender: Option[List[Data.PeopleByGender]]
  )(raw: js.Any)

  object Data {

    final case class PeopleByGender(
      name: PeopleByGender.Name,
      gender: Gender,
      age: Option[Int]
    )(raw: js.Any)

    object PeopleByGender {

      final case class Name(
        firstName: String,
        lastName: Option[String]
      )(raw: js.Any)
    }
  }
}

Now you are able to write your React component in a type-safe way:

// Define your React component
val component = ScalaComponent
  .builder[PeopleByGenderQuery.Props]("PeopleByGender")
  .render_P { props =>
    props.data.personByGender.fold(
      <.div("Error occurred or data is not available yet.")
    ) { people =>
      people.toVdomArray { person =>
        <.div(
          <.div(s"First name: ${person.name.firstName}"),
          person.name.lastName.whenDefined { lastName =>
            <.div(s"Last name: $lastName")
          },
          <.div(s"Gender: ${person.gender}"),
          person.age.whenDefined { age =>
            <.div(s"Age: $age")
          }
        )
      }
    }
  }
  .build

// Declare data query for your component
val graphqlComponent = ReactApollo.graphql(PeopleByGenderQuery).apply(component)

// Create an Apollo client to talk to a GraphQL server
val apolloClient = new ApolloClient(
  link = new ApolloHttpLink(
    // Change it to your server address
    uri = "http://localhost:6789/graphql"
  ),
  cache = new ApolloInMemoryCache()
)

// Put your component inside a GraphQL environment
val apolloProvider = ApolloProvider(apolloClient)(
  graphqlComponent(PeopleByGenderQuery.Variables(Gender.FEMALE))
)

// Render everything, you would need scala-js-dom for this
apolloProvider.renderIntoDOM(dom.document.getElementById("root"))

License

MIT licensed. See LICENSE.