# rescript-urql [![npm](https://img.shields.io/npm/v/@urql/rescript.svg)](https://www.npmjs.com/package/@urql/rescript) [![All Contributors](https://img.shields.io/badge/all_contributors-20-orange.svg)](#contributors) [![Build Status](https://github.com/FormidableLabs/rescript-urql/workflows/rescript-urql%20CI/badge.svg)](https://github.com/FormidableLabs/rescript-urql/actions?query=workflow%3A%22rescript-urql+CI%22) [![Maintenance Status][maintenance-image]](#maintenance-status) ReScript bindings for Formidable's Universal React Query Library, [`urql`](https://github.com/FormidableLabs/urql). > πŸ“£ Please note these bindings were previously maintained by Formidable, but have since been taken over by the ReScript Brazil community. ## ✨Features - βš›οΈ A fully featured GraphQL client for `rescript-react`. - βœ… Compile time type and schema validation. - βš™οΈ Customizable behavior via `exchanges`. - 🎣 Support for `useQuery`, `useMutation`, `useSubscription`, and `useClient` hooks! - ⚑ Support for server-side rendering with Next.js. `rescript-urql` is a GraphQL client for `rescript-react`, allowing you to hook up your components to queries, mutations, and subscriptions. It provides bindings to `urql` that allow you to use the API in ReScript, with the benefits of a sound type system, blazing fast compilation, and opportunities for guided customization. ## πŸ“‹ Documentation - [Getting Started](/docs/getting-started.md) - [Client and Provider](/docs/client-and-provider.md) - [Hooks](/docs/hooks.md) - [Exchanges](/docs/exchanges.md) - [Errors](/docs/error.md) - [Advanced](/docs/advanced.md) ## πŸ’Ύ Installation ### 1. Install `@urql/rescript` alongside its `peerDependencies` and `devDependencies`. ```sh yarn add @urql/rescript urql graphql yarn add gentype --dev ``` We try to keep our bindings as close to latest `urql` as possible. However, `urql` tends to make releases a bit ahead of `rescript-urql`. To get a compatible version, we recommend always staying strictly within this project's `peerDependency` range for `urql`. The `gentype` `devDependency` is a requirement introduced by `urql`'s use of `wonka`. `wonka`'s source uses `@genType` declarations, so when the BuckleScript / ReScript compiler attempts to compile `wonka` in your project, it'll need a local copy of `gentype` to use. #### 1a. **Important note for users of `bs-platform>=8.0.0`**. If using `bs-platform>=8.0.0` you'll need to use [`yarn resolutions`](https://classic.yarnpkg.com/en/docs/selective-version-resolutions/) to specify a specific version of `wonka` to resolve. `urql` has an explicit dependency on latest `wonka` `v4`, which is incompatible with `bs-platform>=8.0.0`. See [this issue](https://github.com/kitten/wonka/issues/85) for more details. In your `package.json`, add the following: ```json "resolutions": { "wonka": "5.0.0-rc.1" } ``` If you're using `npm`, you may need to stay on `bs-platform@7.3.2` until `urql` takes a dependency on `wonka>=5.0.0`. ### 2. Add `@reasonml-community/graphql-ppx`. To get the most out of compile time type checks for your GraphQL queries, mutations, and subscriptions, we use [`@reasonml-community/graphql-ppx`](https://github.com/reasonml-community/graphql-ppx). Add this to your project's `devDependencies`. ```sh yarn add @reasonml-community/graphql-ppx --dev ``` ### 3. Update `bsconfig.json`. Add `@urql/rescript`, `wonka`, and `@reasonml-community/graphql-ppx` to your `bs-dependencies` and `@reasonml-community/graphql-ppx/ppx` to your `ppx_flags` in `bsconfig.json`. ```json { "bs-dependencies": [ "@urql/rescript", "wonka", "@reasonml-community/graphql-ppx" ], "ppx-flags": ["@reasonml-community/graphql-ppx/ppx"] } ``` ### 4. Send an introspection query to your API. Finally, you'll need to send an introspection query to your GraphQl API, using a tool like [`graphql-cli`](https://github.com/Urigo/graphql-cli/). You should generate a file called `graphql_schema.json` at the root of your project that `graphql-ppx` can use to type check your queries. **You should check this file into version control** and keep it updated as your API changes. For additional help, head [here](https://github.com/reasonml-community/graphql-ppx#schema). ```sh npx get-graphql-schema ENDPOINT_URL -j > graphql_schema.json ``` Simply re-run this script at anytime to regenerate the `graphql_schema.json` file according to your latest backend schema. ## πŸ’» Example Projects `rescript-urql` has a nice set of examples showing how to use the hooks and client APIs to get the most out of GraphQL and ReScript in your app – check them out in the `/examples` folder. To run any of the examples, follow these steps. ```sh # 1. Navigate into the example of choice. cd examples/1-execute-query-mutation # 2. Install dependencies. yarn # 3. In one terminal, compile the source in watch mode. yarn start # 4. In another terminal, start the demo app server. yarn start:demo ``` The example will start up at `http://localhost:3000`. Edit the example freely to watch changes take effect. ### Editing `rescript-urql` source files If developing on the main `rescript-urql` source files (i.e. anything in `/src/`) and you want to test the changes in one of the examples, you'll need to do the following: ```sh # Save your changes to source, then take the following steps. # 1. Clean any artifacts from previous builds. yarn clean # 2. Rebuild the source. yarn build # 3. Clean example build and reinstall dependencies. cd examples/2-query yarn clean yarn ``` Since we are `link`ing the examples' dependency on `rescript-urql` to the `src` directory, it's important to clean builds between changes to prevent any stale or erroneous artifacts. ## Getting Involved Please help out by [opening an issue](https://github.com/FormidableLabs/rescript-urql/issues) or [filing a PR](https://github.com/FormidableLabs/rescript-urql/pulls). ## Contributors This project follows the [all contributors spec](https://github.com/kentcdodds/all-contributors). Thanks to these wonderful folks for contributing ([Emoji Key](https://github.com/kentcdodds/all-contributors#emoji-key)):

Parker Ziegler
πŸ’» πŸ“– πŸ‘€ πŸ€”
Khoa Nguyen
πŸ’» πŸ“–
Phil PlΓΌckthun
πŸ€”
Kara Stubbs
πŸ’» ⚠️ πŸ’‘
Marcos Felipe Pimenta Rodrigues
πŸ“–
Gustavo Aguiar
πŸ’» πŸ’‘

Avery Morin
πŸ€” πŸ’» πŸ’‘ πŸ“–
Alain Armand
πŸ’» πŸ’‘
Robin Weser
πŸ“–
Cem Turan
πŸ“–
Huy Nguyen
πŸ“–
Sean Grove
πŸ’» πŸ’‘ πŸ€” πŸ“–

Tomasz Cichocinski
πŸ’» πŸ›
Jovi De Croock
πŸ’»
Corentin Leruth
πŸ“– πŸ’»
Joel Jeddeloh
πŸ’»
hui.liu
πŸ“–
KΓ©vin Combriat
πŸ’» πŸ› πŸ€”

Amirali Esmaeili
πŸ’» πŸ’‘
Alexander Varwijk
πŸ’»