{"id":13499539,"url":"https://github.com/dillonkearns/elm-graphql","last_synced_at":"2025-05-14T03:11:34.903Z","repository":{"id":37239230,"uuid":"112020128","full_name":"dillonkearns/elm-graphql","owner":"dillonkearns","description":"Autogenerate type-safe GraphQL queries in Elm.","archived":false,"fork":false,"pushed_at":"2025-04-17T15:19:49.000Z","size":10984,"stargazers_count":782,"open_issues_count":73,"forks_count":107,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-18T05:53:03.583Z","etag":null,"topics":["elm","graphql"],"latest_commit_sha":null,"homepage":"https://package.elm-lang.org/packages/dillonkearns/elm-graphql/latest","language":"Elm","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dillonkearns.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG-ELM-PACKAGE.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"dillonkearns"}},"created_at":"2017-11-25T17:01:08.000Z","updated_at":"2025-04-17T19:27:58.000Z","dependencies_parsed_at":"2024-09-29T05:20:32.592Z","dependency_job_id":"420c15bb-9c1e-4990-b83f-e4b21e1e46d7","html_url":"https://github.com/dillonkearns/elm-graphql","commit_stats":{"total_commits":1836,"total_committers":48,"mean_commits":38.25,"dds":0.08224400871459692,"last_synced_commit":"e8e4ce52c8129b7d4b9440b359f8480d19be20a5"},"previous_names":[],"tags_count":84,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillonkearns%2Felm-graphql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillonkearns%2Felm-graphql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillonkearns%2Felm-graphql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dillonkearns%2Felm-graphql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dillonkearns","download_url":"https://codeload.github.com/dillonkearns/elm-graphql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059520,"owners_count":22007771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elm","graphql"],"created_at":"2024-07-31T22:00:34.501Z","updated_at":"2025-05-14T03:11:29.894Z","avatar_url":"https://github.com/dillonkearns.png","language":"Elm","funding_links":["https://github.com/sponsors/dillonkearns"],"categories":["Libraries","Elm","Implementations","Code generators"],"sub_categories":["Elm Libraries","Elm","Individual Podcast episodes"],"readme":"# dillonkearns/elm-graphql\n\n[![Build Status](https://github.com/dillonkearns/elm-graphql/workflows/CI/badge.svg)](https://github.com/dillonkearns/elm-graphql/actions?query=branch%3Amaster) [![Elm package](https://img.shields.io/elm-package/v/dillonkearns/elm-graphql.svg)](https://package.elm-lang.org/packages/dillonkearns/elm-graphql/latest/)\n[![npm](https://img.shields.io/npm/v/@dillonkearns/elm-graphql.svg)](https://npmjs.com/package/@dillonkearns/elm-graphql)\n\n![elm-graphql logo](https://res.cloudinary.com/dillonkearns/image/upload/f_png,w_150,q_100/v1603750625/elm-graphql-logo.svg)\n\nWhy use this package over the other available Elm GraphQL packages? This is the only one that\ngenerates type-safe code for your entire schema. Check out this blog post, [Type-Safe \u0026 Composable GraphQL in Elm](https://medium.com/open-graphql/type-safe-composable-graphql-in-elm-b3378cc8d021), to learn more about the motivation for this library. (It's also the only type-safe\nlibrary with Elm 0.18 or 0.19 support, see\n[this discourse thread](https://discourse.elm-lang.org/t/introducing-graphqelm-a-tool-for-type-safe-graphql-queries/472/5?u=dillonkearns)).\n\nI built this package because I wanted to have something that:\n\n1. Gives you type-safe GraphQL queries (if it compiles, it's valid according to the schema),\n2. Creates decoders for you in a seamless and failsafe way, and\n3. Eliminates GraphQL features in favor of Elm language constructs where possible for a simpler UX (for example, GraphQL variables \u0026 fragments should just be Elm functions, constants, lets).\n\nSee an [example in action on Ellie](https://rebrand.ly/graphqelm). See more end-to-end example code in the\n[`examples/`](https://github.com/dillonkearns/elm-graphql/tree/master/examples)\nfolder.\n\n## Overview\n\n`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\n\n```graphql\nquery {\n  human(id: \"1001\") {\n    name\n    homePlanet\n  }\n}\n```\n\nwould look [like this](https://github.com/dillonkearns/elm-graphql/blob/master/examples/src/ExampleFromReadme.elm)\nin `dillonkearns/elm-graphql` (the code in this example that is prefixed with `StarWars` is auto-generated)\n\n```elm\nimport Graphql.Operation exposing (RootQuery)\nimport Graphql.SelectionSet as SelectionSet exposing (SelectionSet)\nimport StarWars.Object\nimport StarWars.Object.Human as Human\nimport StarWars.Query as Query\nimport StarWars.Scalar exposing (Id(..))\n\n\nquery : SelectionSet (Maybe HumanData) RootQuery\nquery =\n    Query.human { id = Id \"1001\" } humanSelection\n\n\ntype alias HumanData =\n    { name : String\n    , homePlanet : Maybe String\n    }\n\n\nhumanSelection : SelectionSet HumanData StarWars.Object.Human\nhumanSelection =\n    SelectionSet.map2 HumanData\n        Human.name\n        Human.homePlanet\n```\n\nGraphQL 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/](http://graphql.org/learn/) is an excellent way to learn the basics.\n\nAfter following the installation instructions to install the [`@dillonkearns/elm-graphql`](https://npmjs.com/package/@dillonkearns/elm-graphql)\nNPM package and the proper Elm packages (see the [Setup section](https://github.com/dillonkearns/elm-graphql#setup) for details).\nOnce you've installed everything, running the `elm-graphql` code generation tool\nis as simple as this:\n\n```bash\nnpx @dillonkearns/elm-graphql https://elm-graphql.onrender.com --base StarWars --output examples/src\n```\n\nIf headers are required, such as a Bearer Token, the `--header` flag can be supplied.\n\n```bash\nnpx @dillonkearns/elm-graphql https://elm-graphql.onrender.com --base StarWars --output examples/src --header 'headerKey: header value'\n```\n\n## Learning Resources\n\n- There is a thorough tutorial in [the `SelectionSet` docs](https://package.elm-lang.org/packages/dillonkearns/elm-graphql/latest/Graphql-SelectionSet). `SelectionSet`s are the core concept in this library, so I recommend reading through the whole page (it's not very long!).\n\n- The [`examples/`](https://github.com/dillonkearns/elm-graphql/tree/master/examples) folder is another great place to start.\n\n- If you want to learn more GraphQL basics, this is a great tutorial, and a short read: [graphql.org/learn/](http://graphql.org/learn/)\n\n- My Elm Conf 2018 talk goes into the philosophy behind `dillonkearns/elm-graphql`\n\n[![Types Without Borders Elm Conf Talk](./assets/types-without-borders.png)](https://www.youtube.com/watch?v=memIRXFSNkU)\n\n([Skip to 13:06](https://youtu.be/memIRXFSNkU?t=786) to go straight to the `dillonkearns/elm-graphql` demo).\n\n- My 10-minute video tutorial on how to leverage Custom Scalars in `elm-graphql` using the Scalar Codecs feature.\n  [![Scalar Codecs Tutorial](./assets/scalar-codecs-tutorial.png)](https://incrementalelm.com/scalar-codecs-tutorial)\n\n* [A Beginner's Guide to GraphQL with Elm](https://medium.com/@zenitram.oiram/a-beginners-guide-to-graphql-with-elm-315b580f0aad) by [@martimatix](https://github.com/martimatix)\n* [The Beginners Guide to elm-graphql by Samuel Wood](https://medium.com/@samote.wood/an-intro-to-elm-graphql-cac214cc048)\n* [Graphqelm: Optional Arguments in a Language Without Optional Arguments](https://medium.com/@zenitram.oiram/graphqelm-optional-arguments-in-a-language-without-optional-arguments-d8074ca3cf74) by [@martimatix](https://github.com/martimatix)\n* [Comprehensive tutorial by the Hasura Team](https://learn.hasura.io/graphql/elm-graphql/introduction)\n\nIf you're wondering why code is generated a certain way, you're likely to find an answer in the [Frequently Asked Questions (FAQ)](https://github.com/dillonkearns/elm-graphql/blob/master/FAQ.md).\n\nThere's a very helpful group of people in the #graphql channel in [the Elm Slack](http://elmlang.herokuapp.com/). Don't hesitate to ask any questions about getting started, best practices, or just general GraphQL in there!\n\n## Setup\n\n`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`.\n\n1. Add [the `dillonkearns/elm-graphql` elm package](http://package.elm-lang.org/packages/dillonkearns/elm-graphql/latest)\n   as a dependency in your `elm.json`. You will also need to make sure that `elm/json` is a dependency of your project\n   since the generated code has lots of JSON decoders in it.\n   ```shell\n   elm install dillonkearns/elm-graphql\n   elm install elm/json\n   ```\n2. Install the `@dillonkearns/elm-graphql` command line tool through npm. This is what you will use to generate Elm code for your API.\n   It is recommended that you save the `@dillonkearns/elm-graphql` command line tool as a dev\n   dependency so that everyone on your project is using the same version.\n\n   ```shell\n   npm install --save-dev @dillonkearns/elm-graphql\n   # you can now run it locally using `npx elm-graphql`,\n   # or by calling it through an npm script as in this project's package.json\n   ```\n\n3. 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:\n\n   ```\n   {\n     \"name\": \"star-wars-elm-graphql-project\",\n     \"version\": \"1.0.0\",\n     \"scripts\": {\n       \"api\": \"elm-graphql https://elm-graphql.onrender.com/api --base StarWars\"\n     }\n   ```\n\n4. With the above in your `package.json`, running `npm run api` will generate `dillonkearns/elm-graphql` code for you to call in `./src/StarWars/`. You can now use the generated code as in this [Ellie example](https://rebrand.ly/graphqelm) or in the [`examples`](https://github.com/dillonkearns/elm-graphql/tree/master/examples) folder.\n\n## Subscriptions Support\n\nYou can do real-time APIs using GraphQL Subscriptions and `dillonkearns/elm-graphql`.\nJust wire in the framework-specific JavaScript code for opening the WebSocket connection\nthrough a port. Here's a [live demo](https://dillonkearns.github.io/elm-graphql/) and its\n[source code](https://github.com/dillonkearns/elm-graphql/tree/master/examples/subscription). The [demo server is running Elixir/Absinthe](https://github.com/dillonkearns/graphqelm-demo).\n\n## Contributors\n\nThank you Mario Martinez ([martimatix](https://github.com/martimatix)) for\nall your feedback, the elm-format PR, and for [the incredible logo design](https://github.com/martimatix/logo-graphqelm/)!\n\nThank you Mike Stock ([mikeastock](https://github.com/mikeastock/)) for\nsetting up Travis CI!\n\nThanks for [the reserved words pull request](https://github.com/dillonkearns/elm-graphql/pull/41) @madsflensted!\n\nA huge thanks to [@xtian](https://github.com/xtian) for doing the vast majority\nof the [0.19 upgrade work](https://github.com/dillonkearns/elm-graphql/pull/60)! :tada:\n\nThank you [Josh Adams (@knewter)](https://github.com/knewter) for the code example for\nSubscriptions with Elixir/Absinthe wired up through Elm ports!\n\nThank you [Romario](https://github.com/romariolopezc) for adding [`OptionalArgument.map`](https://github.com/dillonkearns/elm-graphql/pull/73)!\n\nThank you [Aaron White](https://github.com/aaronwhite) for [your pull request to improve the performance and\nstability of the `elm-format` step](https://github.com/dillonkearns/elm-graphql/pull/87)! 🎉\n\n## Roadmap\n\nAll core features are supported. That is, you can build any query or mutation\nwith your `dillonkearns/elm-graphql`-generated code, and it is guaranteed to be valid according\nto your server's schema.\n\n`dillonkearns/elm-graphql` will generate code for you to generate subscriptions\nand decode the responses, but it doesn't deal with the low-level details for\nhow to send them over web sockets. To do that, you will need to use\ncustom code or a package that knows how to communicate over websockets (or whichever\nprotocol) to setup a subscription with your particular framework. See\n[this discussion](https://github.com/dillonkearns/elm-graphql/issues/43) for why\nthose details are not handled by this library directly.\n\nI would love to hear feedback if you are using GraphQL Subscriptions. In particular,\nI'd love to see live code examples to drive any improvements to the Subscriptions\ndesign. Please ping me on Slack, drop a message in the\n[#graphql](https://elmlang.slack.com/channels/graphql) channel, or open up a\nGithub issue to discuss!\n\nI would like to investigate generating helpers to make pagination simpler\nfor Connections (based on the\n[Relay Cursor Connections Specification](https://relay.dev/graphql/connections.htm)).\nIf you have ideas on this chime in on [this thread](https://github.com/dillonkearns/elm-graphql/issues/29).\n\nSee [the full roadmap on Trello](https://trello.com/b/BCIWtZeL/dillonkearns-elm-graphql).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdillonkearns%2Felm-graphql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdillonkearns%2Felm-graphql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdillonkearns%2Felm-graphql/lists"}