Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update subscriptions.md #1821

Merged
merged 3 commits into from Jul 28, 2021
Merged

Update subscriptions.md #1821

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2fb0317
Update subscriptions.md
andyrichardson Jul 27, 2021
0e020c2
Revert deletion of additional info
andyrichardson Jul 28, 2021
6c7a07d
Update docs/advanced/subscriptions.md
andyrichardson Jul 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
62 changes: 28 additions & 34 deletions docs/advanced/subscriptions.md
View file
Open in desktop
Expand Up @@ -40,26 +40,28 @@ When we define this function it must return an "Observable-like" object, which n
[Observable spec](https://github.com/tc39/proposal-observable), which comes down to having an
object with a `.subscribe()` method accepting an observer.

## Setting up `subscriptions-transport-ws`
## Setting up `graphql-ws`

If your GraphQL API is using [the Apollo Server](https://www.apollographql.com/docs/apollo-server/),
you'll be able to use [Apollo's `subscriptions-transport-ws`
package](https://github.com/apollographql/subscriptions-transport-ws).
For backends supporting `graphql-ws`, we recommend using the [graphql-ws](https://github.com/enisdenjo/graphql-ws) client.

```js
import { Client, defaultExchanges, subscriptionExchange } from 'urql';
import { SubscriptionClient } from 'subscriptions-transport-ws';
import { createClient, defaultExchanges, subscriptionExchange } from 'urql';
import { createClient as createWSClient } from 'graphql-ws';

const subscriptionClient = new SubscriptionClient('ws://localhost/graphql', { reconnect: true });
const wsClient = createWSClient({
url: 'ws://localhost/graphql',
});

const client = new Client({
const client = createClient({
url: '/graphql',
exchanges: [
...defaultExchanges,
subscriptionExchange({
forwardSubscription(operation) {
return subscriptionClient.request(operation);
},
forwardSubscription: (operation) => ({
subscribe: (sink) => ({
unsubscribe: wsClient.subscribe(operation, sink),
}),
}),
}),
],
});
Expand All @@ -69,45 +71,37 @@ In this example, we're creating a `SubscriptionClient`, are passing in a URL and
and are using the `SubscriptionClient`'s `request` method to create a Subscription Observable, which
we return to the `subscriptionExchange` inside `forwardSubscription`.

[Read more about `subscription-transport-ws` on its README.](https://github.com/apollographql/subscriptions-transport-ws/blob/master/README.md)
[Read more on the `graphql-ws` README.](https://github.com/enisdenjo/graphql-ws/blob/master/README.md)

## Setting up `graphql-ws`
## Setting up `subscriptions-transport-ws`

If your GraphQL API server is using [graphql-ws](https://github.com/enisdenjo/graphql-ws),
you'll be able to use it here too!
For backends supporting `subscriptions-transport-ws`, [Apollo's `subscriptions-transport-ws`
package](https://github.com/apollographql/subscriptions-transport-ws) can be used.

> The `subscriptions-transport-ws` package isn't actively maintained. If your API supports the new protocol or you can swap the package out, consider using [`graphql-ws`](#setting-up-graphql-ws) instead.

```js
import { createClient, defaultExchanges, subscriptionExchange } from 'urql';
import { createClient as createWSClient } from 'graphql-ws';
import { Client, defaultExchanges, subscriptionExchange } from 'urql';
import { SubscriptionClient } from 'subscriptions-transport-ws';

const wsClient = createWSClient({
url: 'ws://localhost/graphql',
});
const subscriptionClient = new SubscriptionClient('ws://localhost/graphql', { reconnect: true });

const client = createClient({
const client = new Client({
url: '/graphql',
exchanges: [
...defaultExchanges,
subscriptionExchange({
forwardSubscription(operation) {
return {
subscribe: sink => {
const dispose = wsClient.subscribe(operation, sink);
return {
unsubscribe: dispose,
};
},
};
},
forwardSubscription: (operation) => subscriptionClient.request(operation)
}),
],
});
```

We create a WebSocket client with the necessary options and use the `subscribe` method from it to
create a Subscription Observable, which we return to the `subscriptionExchange` inside `forwardSubscription`.
In this example, we're creating a `SubscriptionClient`, are passing in a URL and some parameters,
andyrichardson marked this conversation as resolved.
Show resolved Hide resolved
and are using the `SubscriptionClient`'s `request` method to create a Subscription Observable, which
we return to the `subscriptionExchange` inside `forwardSubscription`.

[Read more on the `graphql-ws` README.](https://github.com/enisdenjo/graphql-ws/blob/master/README.md)
[Read more about `subscription-transport-ws` on its README.](https://github.com/apollographql/subscriptions-transport-ws/blob/master/README.md)

## React & Preact

Expand Down