graphql-mini-transforms
v5.7.1
Published
Transformers for importing .graphql files in various build tools.
Downloads
179,099
Readme
graphql-mini-transforms
Transformers for importing .graphql files in various build tools.
Installation
yarn add graphql-mini-transforms
Usage
Webpack
This package provides a loader for .graphql
files in Webpack. This loader automatically minifies and adds a unique identifier to each GraphQL document. These features are used by @shopify/webpack-persisted-graphql-plugin
to generate a mapping of identifiers to GraphQL operations for persisted queries.
To use this loader in Webpack, add a rule referencing this loader to your Webpack configuration:
module.exports = {
module: {
rules: [
{
test: /\.(graphql|gql)$/,
use: 'graphql-mini-transforms/webpack-loader',
exclude: /node_modules/,
},
],
},
};
Note that, unlike graphql-tag/loader
, this loader does not currently support exporting multiple operations from a single file. You can, however, import other GraphQL documents containing fragments with #import
comments at the top of the file:
#import './ProductVariantPriceFragment.graphql';
query Product {
product {
variants(first: 10) {
edges {
node {
...ProductVariantId
...ProductVariantPrice
}
}
}
}
}
fragment ProductVariantId on ProductVariant {
id
}
Options
This loader accepts a single option, format
. This option changes the shape of the value exported from .graphql
files. By default, a graphql-typed
DocumentNode
is exported, but you can also provide these alternative formats instead:
simple
: aSimpleDocument
is exported instead. This representation of GraphQL documents is smaller than a fullDocumentNode
, but generally won’t work with normalized GraphQL caches like the one used in Apollo Client.simple-persisted
: likesimple
, but with thesource
property removed. This means that the original document will not be present in your JavaScript at all. This option is only appropriate for apps using “persisted queries”, where only a hash of the query (available as theid
property) is sent to the server.
module.exports = {
module: {
rules: [
{
test: /\.(graphql|gql)$/,
use: 'graphql-mini-transforms/webpack-loader',
exclude: /node_modules/,
options: {format: 'simple'},
},
],
},
};
If this option is set to simple
or simple-persisted
, you should also use the jest-simple
transformer for Jest, and the --export-format simple
flag for graphql-typescript-definitions
.
Rollup / Vite
This package provides a plugin for loading .graphql
files in Rollup.
To use this plugin, add a rule referencing this loader to your Rollup configuration:
// rollup.config.mjs
import {graphql} from 'graphql-mini-transforms/rollup';
export default {
// ...
// Other Rollup config
// ...
plugins: [graphql()],
};
Like the Webpack loader, you can provide a format
option to control the way documents are exported from .graphql
files:
// rollup.config.mjs
import {graphql} from 'graphql-mini-transforms/rollup';
export default {
// ...
// Other Rollup config
// ...
plugins: [graphql({format: 'simple'})],
};
For convenience, a Vite-friendly version of this plugin is also provided:
// vite.config.mjs
import {graphql} from 'graphql-mini-transforms/vite';
export default {
// ...
// Other Vite config
// ...
plugins: [graphql()],
};
Jest
This package also provides a transformer for GraphQL files in Jest. To use the transformer, add a reference to it in your Jest configuration’s transform
option:
module.exports = {
transform: {
'\\.(gql|graphql)$': 'graphql-mini-transforms/jest',
},
};
If you want to get the same output as the format: 'simple'
option of the webpack loader, you can instead use the jest-simple
loader transformer:
module.exports = {
transform: {
'\\.(gql|graphql)$': 'graphql-mini-transforms/jest-simple',
},
};
Prior art
This loader takes heavy inspiration from the following projects:
We wrote something custom in order to get the following benefits:
- Significantly smaller output with no runtime
- Automatically-generated document identifiers
Related projects
- next-plugin-mini-graphql - Provides Next.js support for
.graphql
files usinggraphql-mini-transforms