https://github.com/marko-js/urql
An isomorphic URQL GraphQL client for Marko
https://github.com/marko-js/urql
Last synced: about 2 months ago
JSON representation
An isomorphic URQL GraphQL client for Marko
- Host: GitHub
- URL: https://github.com/marko-js/urql
- Owner: marko-js
- License: mit
- Created: 2021-12-10T22:24:31.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-11T19:08:23.000Z (4 months ago)
- Last Synced: 2025-04-24T00:06:26.560Z (about 2 months ago)
- Language: TypeScript
- Size: 881 KB
- Stars: 8
- Watchers: 6
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
@marko/urql
A wrapper over the URQL GraphQL client for Marko.
# Installation
```console
npm install @marko/urql
```
# How it works
This package exposes 3 tags ``, `` and `` designed to work on both the client and server.
## On the server
When the page is being rendered a request will be made to the GraphQL service and Marko will continue rendering and streaming the page to the browser. On completion of that request Marko will stream the completed HTML to the browser. If the GraphQL query is not under a stateful component Marko will only serialize the data as needed by descendant stateful components and the GraphQL client will not be part of your bundle.
## In the browser
If your GraphQL query is part of a stateful component when the browser receives the final HTML it will also receive the serialized data which will initialize a query cache which will be used for future requests.
## Caching
This package uses query cache where queries are cached by combination of query and variables. Requesting the same query will return the cached results instead of requesting to the server again by default. This behavior can be modified setting the `requestPolicy`.
Available Cache Policies are:
- `cache-first` (the default) prefers cached results and falls back to sending an API request when no prior result is cached.
- `cache-and-network` returns cached results but also always sends an API request, which is perfect for displaying data quickly while keeping it up-to-date.
- `network-only` will always send an API request and will ignore cached results.
- `cache-only` will always return cached results or null.
# Example
```marko
import { gql } from "@marko/urql";
static const QUERY = gql`
query($name: String) {
hello(name: $name)
}
`;
class {
onCreate() {
this.state = { name: "John" }
}
handleClick() {
this.state.name = "Jack"
}
}
<@then|{ data, fetching }|>
Stale
Toggle
${data.hello}
@then>
<@placeholder>
@placeholder>
```
# API
## ``
This central Client manages all of our GraphQL requests and results.
### Attributes
#### `url`
The url of the GraphQL server.
#### `name`
The name of Urql client. This is required when setting up multiple clients.
> Cooresponding `name` need to be set in `` and/or `` as well.
#### `fetch`
This attribute allows you to pass a custom `fetch` implementation.
In the following example we'll add a token to each fetch request that our Client sends to our GraphQL API.
> Note: fetchImp as third parameter is the default implementation based on environment. It is `fetch` API in browser and `make-fetch-happen` in node.
```marko
{
const token = getToken();
return fetch(resource, {
...options,
headers: { authorization: token ? `Bearer ${token}` : '' },
});
})
/>
```
#### `fetchOptions`
This attribute allows you to pass extra options to the fetch function.
#### `requestPolicy`
Set the default cache policy. The default is "cache-first".
## ``
This tag is used to query a GraphQL server for data.
### Attributes
#### `query`
The graphql query to perform.
#### `variables`
Any variables to pass to the query.
#### `requestPolicy`
The cache policy to use with this query request.
#### `timeout`
A time in milliseconds after which the query will be aborted and resolve to a timeout error.
#### `@then|results, revalidate|`
The content to display on query completion. The results object consists of:
- `data` is the data returned from the graphql request
- `error` is any errors that come back from request
- `fetching` is a boolean to indicate if the request is currently in flight
`revalidate` is a function to refresh the current query. By default it uses `network-only` cache policy, but it is overridable by passing `requestPolicy` key on options object passed to it.
#### `@placeholder`
The loading state placeholder to use on initial render.
#### `name`
The name of cooresponding Urql client.
## ``
This tag performs graphql mutations. The content is rendered immediately on mount and provides the `mutate` method that can be used to trigger the mutation. `mutate` takes the variables as first argument and options as second argument.
The results object consists of:
- `data` is the data returned from the graphql mutation
- `error` is any errors that come back from request
- `fetching` is a boolean to indicate if the request is currently in flight
Example:
```marko
import { gql } from "../../../../../../index";
static const MUTATION = gql`
mutation addMessage(
$text: String!
) {
addMessage(text: $text)
}
`;
class {
handleClick(mutate, e) {
mutate({ text: "Hello" });
}
}
Messages
${results.data && results.data.addMessage}
${results.fetching ? "executing" : ""}
Add
```
### Attributes
#### `mutation`
The graphql query to perform.
#### `requestPolicy`
The cache policy to use with this mutation request.
#### `name`
The name of cooresponding Urql client.
# Code of Conduct
This project adheres to the [eBay Code of Conduct](./.github/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.