Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/FormidableLabs/rescript-urql

ReScript bindings for Formidable's Universal React Query Library, urql.
https://github.com/FormidableLabs/rescript-urql

bucklescript graphql graphql-client reasonml reasonreact rescript urql

Last synced: 3 months ago
JSON representation

ReScript bindings for Formidable's Universal React Query Library, urql.

Host: GitHub
URL: https://github.com/FormidableLabs/rescript-urql
Owner: teamwalnut
License: mit
Created: 2018-07-21T23:22:53.000Z (over 6 years ago)
Default Branch: main
Last Pushed: 2024-04-16T14:31:41.000Z (7 months ago)
Last Synced: 2024-04-20T00:49:30.990Z (7 months ago)
Topics: bucklescript, graphql, graphql-client, reasonml, reasonreact, rescript, urql
Language: ReScript
Homepage:
Size: 2.92 MB
Stars: 236
Watchers: 41
Forks: 28
Open Issues: 11
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

awesome-list - rescript-urql

README

# 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 `[email protected]` 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}
💻