Mirror: The small sibling of the graphql package, slimmed down for client-side libraries.
kitten.sh
1<div align="center">
2 <h2 align="center">graphql-web-lite</h2>
3 <p align="center"><strong>The small sibling of the <code>graphql</code> package, slimmed down for client-side libraries</strong></p>
4 <br />
5 <a href="https://npmjs.com/package/graphql-web-lite">
6 <img alt="NPM Version" src="https://img.shields.io/npm/v/graphql-web-lite.svg" />
7 </a>
8 <a href="https://npmjs.com/package/use-interactions">
9 <img alt="License" src="https://img.shields.io/npm/l/graphql-web-lite.svg" />
10 </a>
11 <a href="https://bundlephobia.com/result?p=graphql-web-lite">
12 <img alt="Minified gzip size" src="https://img.shields.io/bundlephobia/minzip/graphql-web-lite.svg?label=gzip%20size" />
13 </a>
14 <br />
15 <br />
16</div>
17
18The `graphql` package serves two purposes in being the reference implementation of the
19[GraphQL specification](https://spec.graphql.org/) and being used as the shared toolkit
20for implementing GraphQL in client-side and server-side JavaScript applications. This
21can cause bloat for client-side apps, where we'd rather choose lower bundlesize impact
22over fidelity.
23
24`graphql-web-lite` is an **experimental** library, providing an alias package that can
25be swapped in for the standard `graphql` package in client-side applications.
26It aims to reduce the size of imports that are in common use by GraphQL clients and
27users, while still providing most `graphql` exports that are used in other contexts.
28
29## Installation
30
31`graphql-web-lite` mirrors the folder structure of the regular `graphql` package and
32includes mostly the same files and imports as the `graphql` package, minus a couple
33that aren't commonly used for client-side GraphQL.
34This offers us several installation options, depending on how the package is aliased
35to the regular `"graphql"` import.
36
37<details>
38<summary><strong>Installation with <code>package.json</code> aliases</strong></summary>
39
40When your dependencies and `node_modules` folder isn't used by a _GraphQL server_ and
41only used by a _GraphQL clients_, you can use a quick and easy npm installation alias.
42In your `package.json` file you can define your `graphql` installation to use
43`graphql-web-lite` instead, which is supported by both Yarn and npm:
44
45```diff
46{
47 "dependencies": {
48- "graphql": "^15.5.0"
49+ "graphql": "npm:graphql-web-lite@^15.5.1000"
50 }
51}
52```
53
54Alternatively, you can run an installation command to alias the package:<br />
55
56```sh
57npm install --save graphql@npm:graphql-web-lite
58# or
59yarn add graphql@npm:graphql-web-lite
60```
61
62When this isn't suitable — for instance, because the same dependencies are shared
63with an API or server-side GraphQL consumer, or you're working inside a monorepo —
64you can try one of the other aliasing techniques below.
65
66</details>
67
68<details>
69<summary><strong>Installation with Webpack aliases</strong></summary>
70
71First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
72package.
73
74```sh
75npm install --save graphql-web-lite
76# or
77yarn add graphql-web-lite
78```
79
80To alias a package in Webpack, an entry must be added to your Webpack
81configuration's `resolve.alias` section. Depending on your implementation,
82the configuration may already contain some keys inside `resolve.alias`, and
83you'd want to add another entry for `"graphql"`.
84
85```js
86const webpackConfig = {
87 // ...
88 resolve: {
89 alias: {
90 graphql: 'graphql-web-lite',
91 },
92 },
93};
94```
95
96</details>
97
98<details>
99<summary><strong>Installation with Next.js</strong></summary>
100
101First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
102package.
103
104```sh
105npm install --save graphql-web-lite
106# or
107yarn add graphql-web-lite
108```
109
110In your [Next.js configuration file](https://nextjs.org/docs/api-reference/next.config.js/introduction),
111under `next.config.js`, you can add an additional `webpack()` function that is
112able to modify Next's Webpack configuration to add an alias for `graphql`.
113
114```js
115module.exports = {
116 webpack(config, { isServer }) {
117 if (!isServer) {
118 config.resolve.alias = {
119 ...config.resolve.alias,
120 graphql: 'graphql-web-lite',
121 };
122 }
123 return config;
124 },
125};
126```
127
128Here we're also ensuring that the alias isn't applied on the server-side, in case
129an API route is using `graphql` for a server-side GraphQL schema.
130
131</details>
132
133<details>
134<summary><strong>Installation with Rollup's alias plugin</strong></summary>
135
136First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
137package.
138
139```sh
140npm install --save graphql-web-lite
141# or
142yarn add graphql-web-lite
143```
144
145In Rollup, the easiest way to add a new alias is to use `@rollup/plugin-alias`.
146We'll have to install this plugin and ensure that every import and deep import
147to `graphql` is aliased to `graphql-web-lite`.
148
149Any Rollup-based build will fail when the import name of the package does not
150match the `name` field in the module's `package.json` file, so this step is
151necessary.
152
153```js
154import alias from '@rollup/plugin-alias';
155
156module.exports = {
157 plugins: [
158 alias({
159 entries: [{ find: 'graphql', replacement: 'graphql-web-lite' }],
160 }),
161 ],
162};
163```
164
165</details>
166
167<details>
168<summary><strong>Installation with Vite</strong></summary>
169
170First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
171package.
172
173```sh
174npm install --save graphql-web-lite
175# or
176yarn add graphql-web-lite
177```
178
179In your [Vite configuration file](https://vitejs.dev/config/#config-file-resolving)
180you may add a new entry for its `resolve.alias` entries. This entry works the same
181as Rollup's alias plugin.
182
183```js
184import { defineConfig } from 'vite';
185
186export default defineConfig({
187 resolve: {
188 alias: {
189 graphql: 'graphql-web-lite',
190 },
191 },
192});
193```
194
195Here we're also ensuring that the alias isn't applied on the server-side, in case
196an API route is using `graphql` for a server-side GraphQL schema.
197
198</details>
199
200<details>
201<summary><strong>Installation with Parcel</strong></summary>
202
203First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
204package.
205
206```sh
207npm install --save graphql-web-lite
208# or
209yarn add graphql-web-lite
210```
211
212In Parcel, we can add an entry in our `package.json` file for an alias. Specifically,
213the `alias` property may contain an object that maps packages to their aliases.
214
215```diff
216{
217 "alias": {
218+ "graphql": "graphql-web-lite"
219 }
220}
221```
222
223</details>
224
225<details>
226<summary><strong>Installation with Jest's module mapping</strong></summary>
227
228First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
229package.
230
231```sh
232npm install --save graphql-web-lite
233# or
234yarn add graphql-web-lite
235```
236
237Jest allows any module names to be remapped using regular expression-based
238mappings. In your Jest config you'll need to add an entry for `graphql` that
239remaps all imports and deep imports to `graphql-web-lite`.
240
241```json
242{
243 "moduleNameMapper": {
244 "graphql(.*)": "graphql-web-lite$1"
245 }
246}
247```
248
249</details>
250
251## Impact & Changes
252
253In short, most utilities, functions, and classes exported by the `graphql`
254package are only used for server-side GraphQL. Some of them have been removed
255in `graphql-web-lite` to discourage its server-side usage, and help bundlers
256exlude them if tree-shaking were to fail.
257
258Most GraphQL clients rely on importing the parser, printer, visitor, and the
259`GraphQLError` class. These have all been modified to reduce their bundlesize
260impact and to remove any support for
261[GraphQL's schema language and type system](https://spec.graphql.org/June2018/#sec-Type-System).
262
263Any debugging calls, development-time warnings, and other non-production code
264is also being transpiled away, and `process.env.NODE_ENV` has been compiled
265away.
266
267<details>
268<summary><strong>Full List of Changes</strong></summary>
269
270| Export | Changes | Notes |
271| -------------------------- | ----------- | ------------------------------------------------------------------- |
272| `getVisitFn` | _unchanged_ | n/a |
273| `visitInParallel` | _unchanged_ | n/a |
274| `BREAK` | _unchanged_ | n/a |
275| `visit` | _modified_ | works recursively and does not detect invalid AST nodes |
276| `print` | _modified_ | won't output any schema nodes and does not detect invalid AST nodes |
277| `printLocation` | _modified_ | won't output source snippets |
278| `printSourceLocation` | _modified_ | won't output source snippets |
279| `parse` | _modified_ | won't parse schema nodes or throw precise syntax errors |
280| `parseType` | _modified_ | won't throw precise syntax errors |
281| `parseValue` | _modified_ | won't throw precise syntax errors |
282| `GraphQLError` | _modified_ | doesn't handle locations and Error stacks |
283| `syntaxError` | _removed_ | n/a |
284| `printType` | _removed_ | n/a |
285| `printSchema` | _removed_ | n/a |
286| `printIntrospectionSchema` | _removed_ | n/a |
287| `lexicographicSortSchema` | _removed_ | n/a |
288| `isSchema` | _removed_ | n/a |
289| `isInterfaceType` | _removed_ | n/a |
290| `getDescription` | _removed_ | n/a |
291| `findDeprecatedUsages` | _removed_ | n/a |
292| `buildSchema` | _removed_ | n/a |
293| `buildASTSchema` | _removed_ | n/a |
294| `assertSchema` | _removed_ | n/a |
295| `assertInterfaceType` | _removed_ | n/a |
296| `assertCompositeType` | _removed_ | n/a |
297| `assertAbstractType` | _removed_ | n/a |
298| `TokenKind` | _removed_ | n/a |
299| `Token` | _removed_ | n/a |
300| `Lexer` | _removed_ | n/a |
301| `GraphQLUnionType` | _removed_ | n/a |
302| `GraphQLInterfaceType` | _removed_ | n/a |
303| `GraphQLInputObjectType` | _removed_ | n/a |
304
305</details>