https://github.com/teamwalnut/rescript-urql
ReScript bindings for Formidable's Universal React Query Library, urql.
https://github.com/teamwalnut/rescript-urql
bucklescript graphql graphql-client reasonml reasonreact rescript urql
Last synced: 10 months ago
JSON representation
ReScript bindings for Formidable's Universal React Query Library, urql.
- Host: GitHub
- URL: https://github.com/teamwalnut/rescript-urql
- Owner: teamwalnut
- License: mit
- Created: 2018-07-21T23:22:53.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-04-22T10:21:18.000Z (almost 2 years ago)
- Last Synced: 2024-12-06T21:23:40.204Z (about 1 year ago)
- Topics: bucklescript, graphql, graphql-client, reasonml, reasonreact, rescript, urql
- Language: ReScript
- Homepage:
- Size: 3.09 MB
- Stars: 238
- Watchers: 38
- Forks: 28
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# rescript-urql
[](https://www.npmjs.com/package/@urql/rescript)
[](#contributors)
[](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
💻