make graphql-ws an optional peer dependency (#2753)

thomasheyenbrock · web-flow · commit bfa90f249be4 · 2022-09-07T09:25:38.000+02:00
* make `graphql-ws` an optional peer dependency

* readme and docs editorials
diff --git a/.changeset/dull-bulldogs-bow.md b/.changeset/dull-bulldogs-bow.md
@@ -0,0 +1,5 @@
+---
+'@graphiql/toolkit': patch
+---
+
+Mark the `graphql-ws` peer dependency as optional (as it's only needed when the fetcher needs to support subscriptions)
diff --git a/packages/graphiql-toolkit/README.md b/packages/graphiql-toolkit/README.md
@@ -2,18 +2,9 @@
 
 # `@graphiql/toolkit`
 
-General purpose library as a dependency of GraphiQL.
-
-A core dependency of the GraphiQL 2.0.0 initiative.
+This is a general purpose library for building GraphQL IDEs. It's being used by other packages like `graphiql` and `@graphiql/react` and also provides utilities that are useful when working with these packages.
 
 ## Docs
 
 - **[`createFetcher`](./docs/create-fetcher.md)** : a utility for creating a `fetcher` prop implementation for HTTP GET, POST including multipart, websockets fetcher
 - more to come!
-
-## Todo
-
-- [x] Begin porting common type definitions used by GraphiQL and it's dependencies
-- [x] `createGraphiQLFetcher` utility for an easier `fetcher`
-- [ ] Migrate over general purpose `graphiql/src/utilities`
-- [ ] Utility to generate json schema spec from `getQueryFacts` for monaco, vscode, etc
diff --git a/packages/graphiql-toolkit/docs/create-fetcher.md b/packages/graphiql-toolkit/docs/create-fetcher.md
@@ -1,28 +1,22 @@
-## Create Fetcher
+# `createGraphiQLFetcher`
 
-a utility for generating a full-featured `fetcher` for GraphiQL including `@stream`, `@defer` `IncrementalDelivery`and `multipart` and subscriptions using `graphql-ws` or the legacy websockets protocol
+A utility for generating a full-featured `fetcher` for GraphiQL including `@stream`, `@defer` `IncrementalDelivery`and `multipart` and subscriptions using `graphql-ws` or the legacy websockets protocol.
 
-under the hood, it uses [`graphql-ws`](https://www.npmjs.com/package/graphql-ws) client and [`meros`](https://www.npmjs.com/package/meros) which act as client reference implementations of the [GraphQL over HTTP Working Group Spec](https://github.com/graphql/graphql-over-http) specification, and the most popular transport spec proposals
+Under the hood, it uses [`graphql-ws`](https://www.npmjs.com/package/graphql-ws) client and [`meros`](https://www.npmjs.com/package/meros) which act as client reference implementations of the [GraphQL over HTTP Working Group Spec](https://github.com/graphql/graphql-over-http) specification, and the most popular transport spec proposals.
 
-### Setup
+## Setup
 
-[`graphiql`](https://npmjs.com/package/graphiql) and thus `react` and `react-dom` should already be installed.
-
-you'll need to install `@graphiql/toolkit`
+You can install `@graphiql/toolkit` using your favorite package manager:
 
 ```bash
 npm install --save @graphiql/toolkit
 ```
 
-```bash
-yarn add @graphiql/toolkit
-```
-
-### Getting Started
+## Getting Started
 
 We have a few flexible options to get you started with the client. It's meant to cover the majority of common use cases with a simple encapsulation.
 
-#### Default HTTP/Multipart IncrementalDelivery Usage
+### Default HTTP/Multipart IncrementalDelivery Usage
 
 Here's a simple example. In this case, a websocket client isn't even initialized, only http (with multipart `@stream` and `@defer` Incremental Delivery support of course!).
 
@@ -41,19 +35,15 @@ export const App = () => <GraphiQL fetcher={fetcher} />;
 ReactDOM.render(document.getElementByID('graphiql'), <App />);
 ```
 
-#### Adding `graphql-ws` websockets subscriptions
+### Adding `graphql-ws` websockets subscriptions
 
-first you'll need to install `graphql-ws` as a peer dependency:
+First you'll need to install `graphql-ws` as a peer dependency:
 
 ```bash
 npm install --save graphql-ws
 ```
 
-```bash
-yarn add graphql-ws
-```
-
-Just by providing the `subscriptionUrl`, you can also generate a `graphql-ws` client. This client now supports both HTTP/Multipart Incremental Delivery for `@defer` and `@stream`, _and_ websockets subscriptions
+Just by providing the `subscriptionUrl`, you can also generate a `graphql-ws` client. This client now supports both HTTP/Multipart Incremental Delivery for `@defer` and `@stream`, _and_ websockets subscriptions.
 
 ```ts
 import * as React from 'react';
@@ -75,25 +65,25 @@ export const App = () => <GraphiQL fetcher={fetcher} />;
 ReactDOM.render(document.getElementByID('graphiql'), <App />);
 ```
 
-You can further customize the `graphql-ws` implementation by creating a custom client instance and providing it as the `wsClient` parameter
+You can further customize the `graphql-ws` implementation by creating a custom client instance and providing it as the `wsClient` parameter.
 
-### Options
+## Options
 
-#### `url` (_required_)
+### `url` (_required_)
 
 This is url used for all `HTTP` requests, and for schema introspection.
 
-#### `subscriptionUrl`
+### `subscriptionUrl`
 
 This generates a `graphql-ws` client using the provided url. Note that a server must be compatible with the new `graphql-ws` subscriptions spec for this to work.
 
-#### `wsClient`
+### `wsClient`
 
-provide your own subscriptions client. bypasses `subscriptionUrl`. In theory, this could be any client using any transport, as long as it matches `graphql-ws` `Client` signature.
+Provide your own subscriptions client. Using this option bypasses `subscriptionUrl`. In theory, this could be any client using any transport, as long as it matches `graphql-ws` `Client` signature.
 
-### `wsConnectionParams`
+## `wsConnectionParams`
 
-provide your initial connection params.
+Provide your initial connection params.
 
 ```ts
 
@@ -108,23 +98,23 @@ const App () {
 }
 ```
 
-#### `legacyWsClient` or `legacyClient`
+### `legacyWsClient` or `legacyClient`
 
-provide a legacy subscriptions client using `subscriptions-transport-ws` protocol. bypasses `subscriptionUrl`. In theory, this could be any client using any transport, as long as it matches `subscriptions-transport-ws` `Client` signature.
+Provide a legacy subscriptions client using `subscriptions-transport-ws` protocol. Using this option bypasses `subscriptionUrl`. In theory, this could be any client using any transport, as long as it matches `subscriptions-transport-ws` `Client` signature.
 
-#### `headers`
+### `headers`
 
-Pass headers to any and all requests
+Specify headers that will be passed to all requests.
 
-#### `fetch`
+### `fetch`
 
-Pass a custom fetch implementation such as `isomorphic-fetch`
+Pass a custom fetch implementation such as `isomorphic-fetch`.
 
-### Customization Examples
+## Customization Examples
 
-#### Custom `wsClient` Example using `graphql-ws`
+### Custom `wsClient` Example using `graphql-ws`
 
-Just by providing the `wsClient`
+This example passes a `graphql-ws` client to the `wsClient` option:
 
 ```ts
 import * as React from 'react';
@@ -150,11 +140,11 @@ export const App = () => <GraphiQL fetcher={fetcher} />;
 ReactDOM.render(document.getElementByID('graphiql'), <App />);
 ```
 
-#### Custom `legacyClient` Example
+### Custom `legacyClient` Example
 
 (not recommended)
 
-By providing the `legacyClient` you can support a `subscriptions-transport-ws` client implementation, or equivalent
+By providing the `legacyClient` you can support a `subscriptions-transport-ws` client implementation, or equivalent:
 
 ```ts
 import * as React from 'react';
@@ -177,21 +167,15 @@ export const App = () => <GraphiQL fetcher={fetcher} />;
 ReactDOM.render(document.getElementByID('graphiql'), <App />);
 ```
 
-you will need to install the client separately:
-
-```bash
-yarn add subscriptions-transport-ws
-```
+Note that you will need to install the client separately:
 
 ```bash
 npm install --save subscriptions-transport-ws
 ```
 
-and instantiate a client instance following their readme, and pass it as `legacyWsClient`.
-
-#### Custom `fetcher` Example
+### Custom `fetcher` Example
 
-For SSR, we might want to use something like `isomorphic-fetch`
+For SSR, we might want to use something like `isomorphic-fetch`:
 
 ```ts
 import * as React from 'react';
diff --git a/packages/graphiql-toolkit/package.json b/packages/graphiql-toolkit/package.json
@@ -33,6 +33,11 @@
     "graphql": "^15.5.0 || ^16.0.0",
     "graphql-ws": ">= 4.5.0"
   },
+  "peerDependenciesMeta": {
+    "graphql-ws": {
+      "optional": true
+    }
+  },
   "keywords": [
     "graphql",
     "graphiql"

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@graphiql/toolkit': patch
 +---
++
 +Mark the `graphql-ws` peer dependency as optional (as it's only needed when the fetcher needs to support subscriptions)