graphql-web-lite

The small sibling of the graphql package, slimmed down for client-side libraries


NPM Version License Minified gzip size

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` is an **experimental** library, providing 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. ## 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": "^15.5.0" + "graphql": "npm:graphql-web-lite@^15.5.1001" } } ``` 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 | | -------------------------- | ----------- | ------------------------------------------------------------------- | | `getVisitFn` | _unchanged_ | n/a | | `visitInParallel` | _unchanged_ | n/a | | `BREAK` | _unchanged_ | n/a | | `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 | | `syntaxError` | _removed_ | n/a | | `printType` | _removed_ | n/a | | `printSchema` | _removed_ | n/a | | `printIntrospectionSchema` | _removed_ | n/a | | `lexicographicSortSchema` | _removed_ | n/a | | `isSchema` | _removed_ | n/a | | `isInterfaceType` | _removed_ | n/a | | `getDescription` | _removed_ | n/a | | `findDeprecatedUsages` | _removed_ | n/a | | `buildSchema` | _removed_ | n/a | | `buildASTSchema` | _removed_ | n/a | | `assertSchema` | _removed_ | n/a | | `assertInterfaceType` | _removed_ | n/a | | `assertCompositeType` | _removed_ | n/a | | `assertAbstractType` | _removed_ | n/a | | `TokenKind` | _removed_ | n/a | | `Token` | _removed_ | n/a | | `Lexer` | _removed_ | n/a | | `GraphQLUnionType` | _removed_ | n/a | | `GraphQLInterfaceType` | _removed_ | n/a | | `GraphQLInputObjectType` | _removed_ | n/a |