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, simple. This option changes the shape of the value exported from .graphql files. By default, a graphql-typed DocumentNode is exported, but when simple is set to true, a SimpleDocument is exported instead. This representation of GraphQL documents is smaller than a full DocumentNode, but generally won’t work with normalized GraphQL caches.

module.exports = {
  module: {
    rules: [
      {
        test: /\.(graphql|gql)$/,
        use: 'graphql-mini-transforms/webpack-loader',
        exclude: /node_modules/,
        options: {simple: true},
      },
    ],
  },
};

If this option is set to true, 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 simple: true option to enable the SimpleDocument export format:

// rollup.config.mjs

import {graphql} from 'graphql-mini-transforms/rollup';

export default {
  // ...
  // Other Rollup config
  // ...
  plugins: [graphql({simple: true})],
};

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 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:

• graphql-tag and graphql-persisted-document-loader
• graphql-loader

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 using graphql-mini-transforms