Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/0no-co/graphql-web-lite
The small sibling of the graphql package, slimmed down for client-side libraries.
https://github.com/0no-co/graphql-web-lite
graphql
Last synced: 23 days ago
JSON representation
The small sibling of the graphql package, slimmed down for client-side libraries.
- Host: GitHub
- URL: https://github.com/0no-co/graphql-web-lite
- Owner: 0no-co
- License: mit
- Created: 2021-08-20T13:15:21.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-04T10:20:06.000Z (about 2 months ago)
- Last Synced: 2024-11-04T10:21:24.643Z (about 2 months ago)
- Topics: graphql
- Language: JavaScript
- Homepage:
- Size: 374 KB
- Stars: 160
- Watchers: 7
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
graphql-web-lite
The small sibling of the graphql package, slimmed down for client-side libraries
The `graphql` package serves two purposes in being the reference implementation of the
[GraphQL specification](https://spec.graphql.org/) and being used as the shared toolkit
for implementing GraphQL in client-side and server-side JavaScript applications. This
can cause bloat for client-side apps, where we'd rather choose lower bundlesize impact
over fidelity.
`graphql-web-lite` provides an alias package that can be swapped in for the standard
`graphql` package in client-side applications.
It aims to reduce the size of imports that are in common use by GraphQL clients and
users, while still providing most `graphql` exports that are used in other contexts.
It replaces the default `language` exports with
[`@0no-co/graphql.web`](https://github.com/0no-co/graphql.web) for a leaner
parser, printer, and visitor, which only support the GraphQL query language and
are tested to 100% coverage and built to match GraphQL.js’ performance.
In an average app using the GraphQL library for a GraphQL client aliasing this
package could save you 7kB gzip effortlessly.
> **Note:** If you’re using `@urql/core@^4` you’re already benefitting from
> `@0no-co/graphql.web`’s size reduction and aliasing `graphql-web-lite` will
> only benefit you if you import from `graphql` in any of your other code or
> libraries.
## Installation
`graphql-web-lite` mirrors the folder structure of the regular `graphql` package and
includes mostly the same files and imports as the `graphql` package, minus a couple
that aren't commonly used for client-side GraphQL.
This offers us several installation options, depending on how the package is aliased
to the regular `"graphql"` import.
Installation with package.json aliases
When your dependencies and `node_modules` folder isn't used by a _GraphQL server_ and
only used by a _GraphQL clients_, you can use a quick and easy npm installation alias.
In your `package.json` file you can define your `graphql` installation to use
`graphql-web-lite` instead, which is supported by both Yarn and npm:
```diff
{
"dependencies": {
- "graphql": "^16.6.0"
+ "graphql": "npm:graphql-web-lite@^16.6.0-3"
}
}
```
Alternatively, you can run an installation command to alias the package:
```sh
npm install --save graphql@npm:graphql-web-lite
# or
yarn add graphql@npm:graphql-web-lite
```
When this isn't suitable — for instance, because the same dependencies are shared
with an API or server-side GraphQL consumer, or you're working inside a monorepo —
you can try one of the other aliasing techniques below.
Installation with Webpack aliases
First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
package.
```sh
npm install --save graphql-web-lite
# or
yarn add graphql-web-lite
```
To alias a package in Webpack, an entry must be added to your Webpack
configuration's `resolve.alias` section. Depending on your implementation,
the configuration may already contain some keys inside `resolve.alias`, and
you'd want to add another entry for `"graphql"`.
```js
const webpackConfig = {
// ...
resolve: {
alias: {
graphql: 'graphql-web-lite',
},
},
};
```
Installation with Next.js
First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
package.
```sh
npm install --save graphql-web-lite
# or
yarn add graphql-web-lite
```
In your [Next.js configuration file](https://nextjs.org/docs/api-reference/next.config.js/introduction),
under `next.config.js`, you can add an additional `webpack()` function that is
able to modify Next's Webpack configuration to add an alias for `graphql`.
```js
module.exports = {
webpack(config, { isServer }) {
if (!isServer) {
config.resolve.alias = {
...config.resolve.alias,
graphql: 'graphql-web-lite',
};
}
return config;
},
};
```
Here we're also ensuring that the alias isn't applied on the server-side, in case
an API route is using `graphql` for a server-side GraphQL schema.
Installation with Rollup's alias plugin
First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
package.
```sh
npm install --save graphql-web-lite
# or
yarn add graphql-web-lite
```
In Rollup, the easiest way to add a new alias is to use `@rollup/plugin-alias`.
We'll have to install this plugin and ensure that every import and deep import
to `graphql` is aliased to `graphql-web-lite`.
Any Rollup-based build will fail when the import name of the package does not
match the `name` field in the module's `package.json` file, so this step is
necessary.
```js
import alias from '@rollup/plugin-alias';
module.exports = {
plugins: [
alias({
entries: [{ find: 'graphql', replacement: 'graphql-web-lite' }],
}),
],
};
```
Installation with Vite
First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
package.
```sh
npm install --save graphql-web-lite
# or
yarn add graphql-web-lite
```
In your [Vite configuration file](https://vitejs.dev/config/#config-file-resolving)
you may add a new entry for its `resolve.alias` entries. This entry works the same
as Rollup's alias plugin.
```js
import { defineConfig } from 'vite';
export default defineConfig({
resolve: {
alias: {
graphql: 'graphql-web-lite',
},
},
});
```
Here we're also ensuring that the alias isn't applied on the server-side, in case
an API route is using `graphql` for a server-side GraphQL schema.
Installation with Parcel
First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
package.
```sh
npm install --save graphql-web-lite
# or
yarn add graphql-web-lite
```
In Parcel, we can add an entry in our `package.json` file for an alias. Specifically,
the `alias` property may contain an object that maps packages to their aliases.
```diff
{
"alias": {
+ "graphql": "graphql-web-lite"
}
}
```
Installation with Jest's module mapping
First, we'll need to install `graphql-web-lite` _alongside_ the regular `graphql`
package.
```sh
npm install --save graphql-web-lite
# or
yarn add graphql-web-lite
```
Jest allows any module names to be remapped using regular expression-based
mappings. In your Jest config you'll need to add an entry for `graphql` that
remaps all imports and deep imports to `graphql-web-lite`.
```json
{
"moduleNameMapper": {
"graphql(.*)": "graphql-web-lite$1"
}
}
```
## Impact & Changes
In short, most utilities, functions, and classes exported by the `graphql`
package are only used for server-side GraphQL. Some of them have been removed
in `graphql-web-lite` to discourage its server-side usage, and help bundlers
exlude them if tree-shaking were to fail.
Most GraphQL clients rely on importing the parser, printer, visitor, and the
`GraphQLError` class. These have all been modified to reduce their bundlesize
impact and to remove any support for
[GraphQL's schema language and type system](https://spec.graphql.org/June2018/#sec-Type-System).
Any debugging calls, development-time warnings, and other non-production code
is also being transpiled away, and `process.env.NODE_ENV` has been compiled
away.
Full List of Changes
| Export | Changes | Notes |
| --------------------- | ---------- | ------------------------------------------------------------------- |
| `visit` | _modified_ | works recursively and does not detect invalid AST nodes |
| `print` | _modified_ | won't output any schema nodes and does not detect invalid AST nodes |
| `printLocation` | _modified_ | won't output source snippets |
| `printSourceLocation` | _modified_ | won't output source snippets |
| `parse` | _modified_ | won't parse schema nodes or throw precise syntax errors |
| `parseType` | _modified_ | won't throw precise syntax errors |
| `parseValue` | _modified_ | won't throw precise syntax errors |
| `GraphQLError` | _modified_ | doesn't handle locations and Error stacks |
### Bundlesize Impact
Most GraphQL client-side libraries use the following common set of imports from the `graphql` library.
```js
export { BREAK, isSelectionNode, parse, print, GraphQLError, Kind, visit } from 'graphql';
```
The minzipped size of the imports is about `10kB` in a given output bundle, which assumes all the above imports are
in use. When `graphql-web-lite` replaces the `graphql` package the minzipped size drops to about `3kB`.