![Maintenance Status][maintenance-image]
ReScript bindings for Formidable's Universal React Query Library, urql
.
π£ Please note these bindings were previously maintained by Formidable, but have since been taken over by the ReScript Brazil community.
- βοΈ A fully featured GraphQL client for
rescript-react
. - β Compile time type and schema validation.
- βοΈ Customizable behavior via
exchanges
. - π£ Support for
useQuery
,useMutation
,useSubscription
, anduseClient
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.
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.
If using bs-platform>=8.0.0
you'll need to use yarn 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 for more details.
In your package.json
, add the following:
"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
.
To get the most out of compile time type checks for your GraphQL queries, mutations, and subscriptions, we use @reasonml-community/graphql-ppx
. Add this to your project's devDependencies
.
yarn add @reasonml-community/graphql-ppx --dev
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
.
{
"bs-dependencies": [
"@urql/rescript",
"wonka",
"@reasonml-community/graphql-ppx"
],
"ppx-flags": ["@reasonml-community/graphql-ppx/ppx"]
}
Finally, you'll need to send an introspection query to your GraphQl API, using a tool like 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.
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.
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.
# 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.
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:
# 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.
Please help out by opening an issue or filing a PR.
This project follows the all contributors spec. Thanks to these wonderful folks for contributing (Emoji Key):