(Formerly Graphqelm, read about why the name changed.)
Looking to upgrade to Elm 0.19? Take a look at the dillonkearns/elm-graphql
Elm 0.19 upgrade guide.
Why use this package over the other available Elm GraphQL packages? This is the only one that generates type-safe code for your entire schema. (It's also the only type-safe library with Elm 0.18 or 0.19 support, see this discourse thread ).
I built this package because I wanted to have something that:
- Gives you type-safe GraphQL queries (if it compiles, it's valid according to the schema),
- Creates decoders for you in a seamless and failsafe way, and
- Eliminates GraphQL features in favor of Elm language constructs where possible for a simpler UX (for example, GraphQL variables & fragments should just be Elm functions, constants, lets).
See an example in action on Ellie.
You can do real-time APIs using GraphQL Subscriptions and dillonkearns/elm-graphql
.
Just wire in the framework-specific JavaScript code for opening the WebSocket connection
through a port. Here's a live demo and its
source code.
The demo server is running Elixir/Absinthe.
See more end-to-end example code in the
examples/
folder.
dillonkearns/elm-graphql
is an Elm package and accompanying command-line code generator that creates type-safe Elm code for your GraphQL endpoint. You don't write any decoders for your API with dillonkearns/elm-graphql
, instead you simply select which fields you would like, similar to a standard GraphQL query but in Elm. For example, this GraphQL query
query {
human(id: "1001") {
name
}
}
would look like this in dillonkearns/elm-graphql
(the code in this example that is prefixed with StarWars
is auto-generated)
import Graphql.Operation exposing (RootQuery)
import Graphql.SelectionSet exposing (SelectionSet, with)
import StarWars.Object
import StarWars.Object.Human as Human
import StarWars.Query as Query
type alias Response =
{ vader : Maybe Human }
query : SelectionSet Response RootQuery
query =
Query.selection Response
|> with (Query.human { id = StarWars.Scalar.Id "1001" } humanSelection)
type alias Human =
{ name : String }
humanSelection : SelectionSet Human Human.Human
humanSelection =
Human.selection Human
|> with Human.name
GraphQL and Elm are a perfect match because GraphQL is used to enforce the types that your API takes as inputs and outputs, much like Elm's type system does within Elm. elm-graphql
simply bridges this gap by making your Elm code aware of your GraphQL server's schema. If you are new to GraphQL, graphql.org/learn/ is an excellent way to learn the basics.
After installing the command line tool and Elm package, running elm-graphql
just looks like
elm-graphql https://elm-graphql.herokuapp.com --base Swapi --output examples/src
If headers are required, such as a Bearer Token, the --header
flag can be supplied.
elm-graphql https://elm-graphql.herokuapp.com --base Swapi --output examples/src 'headerKey: header value'
If you're just starting out, here are some great resources:
(Skip to 13:06 to go straight to the dillonkearns/elm-graphql
demo).
- There are a couple of chapters so far in The Official
dillonkearns/elm-graphql
Gitbook - A Beginner's Guide to GraphQL with Elm by @martimatix
- Graphqelm: Optional Arguments in a Language Without Optional Arguments by @martimatix
If you're wondering why code is generated a certain way, you're likely to find an answer in the Frequently Asked Questions (FAQ).
There's a very helpful group of people in the #graphql channel in the Elm Slack. Don't hesitate to ask any questions about getting started, best practices, or just general GraphQL in there!
dillonkearns/elm-graphql
generates Elm code that allows you to build up type-safe GraphQL requests. Here are the steps to setup dillonkearns/elm-graphql
.
-
Add the
dillonkearns/elm-graphql
elm package as a dependency in yourelm-package.json
. You will also need to make sure thatelm/json
is a dependency of your project since the generated code has lots of JSON decoders in it.elm install dillonkearns/elm-graphql elm install elm/json
-
Install the
@dillonkearns/elm-graphql
command line tool through npm. This is what you will use to generate Elm code for your API. It is recommended that you save the@dillonkearns/elm-graphql
command line tool as a dev dependency so that everyone on your project is using the same version.npm install --save-dev @dillonkearns/elm-graphql # you can now run it locally with the ./node_modules/.bin/elm-graphql binary, # or by calling it through an npm script as in this project's package.json
-
Run the
@dillonkearns/elm-graphql
command line tool installed above to generate your code. If you used the--save-dev
method above, you can simply create a script in your package.json like the following:{ "name": "star-wars-elm-graphql-project", "version": "1.0.0", "scripts": { "api": "elm-graphql https://elm-graphql.herokuapp.com/api --base StarWars" }
-
With the above in your
package.json
, runningnpm run api
will generatedillonkearns/elm-graphql
code for you to call in./src/StarWars/
. You can now use the generated code as in this Ellie example or in theexamples
folder.
Thank you Mario Martinez (martimatix) for all your feedback, the elm-format PR, and for the incredible logo design!
Thank you Mike Stock (mikeastock) for setting up Travis CI!
Thanks for the reserved words pull request @madsflensted!
A huge thanks to @xtian for doing the vast majority of the 0.19 upgrade work! 🎉
Thank you [Josh Adams (@knewter)][https://github.com/knewter] for the code example for Subscriptions with Elixir/Absinthe wired up through Elm ports!
Thank you Romario for adding OptionalArgument.map
!
All core features are supported. That is, you can build any query or mutation
with your dillonkearns/elm-graphql
-generated code, and it is guaranteed to be valid according
to your server's schema.
dillonkearns/elm-graphql
will generate code for you to generate subscriptions
and decode the responses, but it doesn't deal with the low-level details for
how to send them over web sockets. To do that, you will need to use
custom code or a package that knows how to communicate over websockets (or whichever
protocol) to setup a subscription with your particular framework. See
this discussion for why
those details are not handled by this library directly.
I would love to hear feedback if you are using GraphQL Subscriptions. In particular, I'd love to see live code examples to drive any improvements to the Subscriptions design. Please ping me on Slack, drop a message in the #graphql channel, or open up a Github issue to discuss!
I would like to investigate generating helpers to make pagination simpler for Connections (based on the Relay Cursor Connections Specification). If you have ideas on this chime in on this thread.