Skip to content

Commit 399216e

Browse files
n1ru4lsaihaj
n1ru4l
and
saihaj
authored
docs: comparison with helix and apollo-server (#1586)
* docs: comparison with helix and apollo-server * Apply suggestions from code review Co-authored-by: Saihajpreet Singh <[email protected]> * fix: typo Co-authored-by: Saihajpreet Singh <[email protected]>
1 parent 3fca6e3 commit 399216e

File tree

3 files changed

+159
-0
lines changed

3 files changed

+159
-0
lines changed

‎website/routes.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,9 @@ export function getDocsV3Routes(): IRoutes {
109109
integrations: {
110110
$name: 'Integrations',
111111
},
112+
comparison: {
113+
$name: 'Comparison',
114+
},
112115
migration: {
113116
$name: 'Migration from',
114117
},

‎website/v3/docs/comparison.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
id: comparison
3+
title: Comparison with other JavaScript GraphQL server libraries
4+
sidebar_label: Comparison
5+
---
6+
7+
## GraphQL Yoga and Apollo Server
8+
9+
This comparison highlights the main differences when using Yoga instead of Apollo Server.
10+
11+
### No Framework-specific Packages
12+
13+
One of the goals of `graphql-yoga` is to have as few `graphql-yoga` packages as possible.
14+
Yoga is designed around the W3C Request/Response specification (often just referred to as ["Fetch API"](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)),
15+
which is already adopted by deno, cloudflare workers, and browsers.
16+
17+
For Node.js environments and frameworks (which unfortunately do not have full W3C Request/Response support), graphql-yoga comes with a small compatibility layer for making it work.
18+
19+
You only need to search for [`apollo-server-` on NPM](https://www.npmjs.com/search?q=apollo-server-) to see how many variants and packages there are for apollo and how hard it is to maintain.
20+
21+
### Run anywhere
22+
23+
As mentioned in the above paragraph `graphql-yoga` is built around W3C Request/Response which is supported in all major serverless/worker/"serverful" JavaScript environments.
24+
Apollo Server plans to drop active support for cloudflare workers and [pushes it onto the community](https://github.com/apollographql/apollo-server/issues/6034).
25+
GraphQL Yoga will continuously support all platforms and runtimes and
26+
Furthermore, Yoga has a full end to end testing suite that actually deploys to all those runtimes in order to ensure integrity and prevent unexpected issues.
27+
28+
### Powerful Plugin System
29+
30+
Envelop’s powerful GraphQL plugin system, that is unfortunately not fully compatible with Apollo Server.
31+
There is still no further follow-up from the apollo maintainers over [on the Apollo Server and envelop discussion](https://github.com/apollographql/apollo-server/discussions/5541).
32+
33+
GraphQL Yoga builds upon envelop and, futhrermore, has a default plugin preset enabled for ensuring best practices for a performant (parse and validation caching) and secure GraphQL (e.g. though error masking) server by default.
34+
If you want to opt-out of some or all of these plugins that is also possible.
35+
36+
Yoga is fully customizable for your needs!
37+
38+
You can find a list of all available Envelop plugins over on [the envelop plugin hub](https://www.envelop.dev/plugins).
39+
40+
### Full Support of the GraphQL over HTTP specification
41+
42+
GraphQL Yoga is fully compatible with the GraphQL over HTTP specification (including the incremental delivaery over HTTP specification).
43+
44+
### File Uploads
45+
46+
GraphQL Yoga supports [file uploads out of the box](/v3/docs/features/file-uploads#enable-file-uploads-in-graphql-yoga).
47+
48+
### GraphQL Subscriptions over Server-Sent-Events (SSE)
49+
50+
GraphQL Yoga supports [GraphQL Subscriptions over Server-Sent-Events (SSE)](/v3/docs/features/subscriptions#subscriptions) out of the box without the need of any additional libraries.
51+
52+
### Bundle Size and lean Dependencies
53+
54+
For serverless/edge (service worker) environments, the size of the server code can be crucial for cold-start time and performance.
55+
56+
Here you can see a comparison of bundle sizes:
57+
58+
- [https://bundlephobia.com/package/[email protected]](Bundlephobia graphql-yoga)
59+
- [https://bundlephobia.com/package/[email protected]](Bundlephobia apollo-server-micro)
60+
61+
GraphQL Yoga only has a fraction of the dependencies of Apollo Server, and in general is much smaller.
62+
63+
- [Dependency visualizer `graphql-yoga`](https://npm.anvaka.com/#/view/2d/graphql-yoga)
64+
- [Dependency visualizer `apollo-server-micro`](https://npm.anvaka.com/#/view/2d/apollo-server-micro)
65+
66+
GraphQL Yogas APIs are designed for code-splitting and supported by popular bundlers.
67+
68+
## GraphQL Yoga and GraphQL Helix
69+
70+
We are maintainers of both libraries today.
71+
72+
The Guild initially adopted, improved, and recommended `graphql-helix`.
73+
74+
While working on it, we realized that it to some extent allowed building more extensible GraphQL server set-ups, but on the other hand, required boilerplate code and isn't easily adoptable by new GraphQL developers.
75+
We also tried adding support for other environments such as cloudflare workers, but adding it as an after-thought wasn't that straightforward.
76+
Eventually, after a lot of trying we figured that the approach of adding it as an after-thought is the actual limitation, and instead of the other way around (W3C Request/Response first, Node.js HTTP Response/Request as a light-weight layer on top) might be a better solution.
77+
78+
This put us in a difficult position.
79+
The Guild does not own `graphql-helix` and we did not want to do drastic changes to it, without verifying that it actually works.
80+
At the same time we were already building `graphql-yoga` based on helix. So we decided to actually do this experiment within graphql-yoga and remove helix as a dependency from yoga.
81+
82+
Today we can happily say that it worked out fine!
83+
84+
Today we recommend `graphql-yoga` over `graphql-helix`, if you want a batteries-included solution for GraphQL server development.
85+
86+
GraphQL Yoga is easier to get started, has nicer defaults, and requires less boilerplate while giving you the same extensibility as `graphql-helix`!

‎website/v3/docs/migration/migration-from-apollo-server.mdx‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,73 @@ For example, if you are using **Express**, you should remove the standalone HTTP
6666
- server.applyMiddleware({ app })
6767
+ app.use('/graphql', yoga)
6868
```
69+
70+
## Batched Queries/Requests
71+
72+
Batched queries is a practice first supported and made popular by the Apollo ecosystem.
73+
The idea of batched query operations is to reduce the number of network requests by grouping them together.
74+
This is achieved by slightly delaying the HTTP request in order to gather all the query operations that are executed shortly after each other.
75+
76+
GraphQL Yoga does not support batched queries for the following reasons:
77+
78+
**_All batched queries are as slow as the longest running individual query._**
79+
80+
Because the GraphQL server does not start sending a response to the client until all the queries are completed, a slow query will prevent a faster query result to be already processed/shown to the end user.
81+
82+
**_Batched queries can ba achieved by componsing multiple GraphQL fragments/operation into a single one._**
83+
84+
Instead of having two operations:
85+
86+
```graphql
87+
query A {
88+
viewer {
89+
id
90+
name
91+
}
92+
}
93+
```
94+
95+
```graphql
96+
query B($postId: ID!) {
97+
post(id: $postId) {
98+
id
99+
title
100+
}
101+
}
102+
```
103+
104+
These operations can be combined into a single operation:
105+
106+
```graphql
107+
query AB($postId: ID!) {
108+
viewer {
109+
id
110+
name
111+
}
112+
post(id: $postId) {
113+
id
114+
title
115+
}
116+
}
117+
```
118+
119+
Furthermore, if you want a partial of the GraphQL operation to arrive at the client as soon as possible, you can use the `@defer` directive.
120+
121+
```graphql
122+
query AB($postId: ID!) {
123+
... on Query @defer(label: "A") {
124+
viewer {
125+
id
126+
name
127+
}
128+
}
129+
... on Query @defer(label: "A") {
130+
post(id: $postId) {
131+
id
132+
title
133+
}
134+
}
135+
}
136+
```
137+
138+
You can learn more on how to get the best out of this in our ["Unlease the power of Fragments with GraphQL Codegen" article](https://the-guild.dev/blog/unleash-the-power-of-fragments-with-graphql-codegen).

0 commit comments

Comments
 (0)