# graphql-mini-transforms

> Transformers for importing .graphql files in various build tools.

Latest version **5.7.1** (published 2024-08-01) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install graphql-mini-transforms
pnpm add graphql-mini-transforms
yarn add graphql-mini-transforms
bun add graphql-mini-transforms
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 5.7.1 |
| Published | 2024-08-01 |
| First published | 2019-04-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.12.0 |
| Dependencies | 4 |
| Unpacked size | 62 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1681 |
| Author | Shopify Inc. |
| Maintainers | shopify-dep |

## Links

- npm: https://www.npmjs.com/package/graphql-mini-transforms
- Repository: https://github.com/Shopify/quilt
- Homepage: https://github.com/Shopify/quilt/blob/main/packages/graphql-mini-transforms/README.md
- Issues: https://github.com/Shopify/quilt/issues
- npm.io page: https://npm.io/package/graphql-mini-transforms

## Dependencies (4)

- [graphql](https://npm.io/package/graphql.md) >=14.5.0 <17.0.0
- [fs-extra](https://npm.io/package/fs-extra.md) ^9.1.0
- [graphql-typed](https://npm.io/package/graphql-typed.md) ^2.3.0
- [@jest/transform](https://npm.io/package/@jest/transform.md) >= 27 <29

## Recent versions

- 5.7.1 (latest) — 2024-08-01
- 0.0.0-snapshot-20240620045713 (snapshot) — 2024-06-20
- 6.0.0-a3-beta.1 (next) — 2022-06-09
- 4.0.0-webpack-5-beta.4 (beta) — 2021-06-09
- 5.7.0 — 2024-07-16
- 5.6.0 — 2024-06-11
- 5.5.0 — 2024-06-10
- 5.4.0 — 2024-06-06
- 5.3.5 — 2024-05-31
- 0.0.0-snapshot-20240531073328 — 2024-05-31
- 5.3.4 — 2024-05-02
- 5.3.3 — 2024-04-16
- 0.0.0-snapshot-20240416154657 — 2024-04-16
- 5.3.2 — 2023-11-06
- 0.0.0-snapshot-20231019204709 — 2023-10-19
- … 64 more at https://npm.io/package/graphql-mini-transforms/versions

## README

# `graphql-mini-transforms`

[![Build Status](https://github.com/Shopify/quilt/workflows/Node-CI/badge.svg?branch=main)](https://github.com/Shopify/quilt/actions?query=workflow%3ANode-CI)
[![Build Status](https://github.com/Shopify/quilt/workflows/Ruby-CI/badge.svg?branch=main)](https://github.com/Shopify/quilt/actions?query=workflow%3ARuby-CI)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md) [![npm version](https://badge.fury.io/js/graphql-mini-transforms.svg)](https://badge.fury.io/js/graphql-mini-transforms.svg)

Transformers for importing .graphql files in various build tools.

## Installation

```bash
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`](https://github.com/Shopify/sewing-kit/tree/main/packages/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:

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

Note that, unlike [`graphql-tag/loader`](https://github.com/apollographql/graphql-tag#webpack-preprocessing-with-graphql-tagloader), 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:

```graphql
#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`: 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 like the one used in Apollo Client.
- `simple-persisted`: like `simple`, but with the `source` 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 the `id` property) is sent to the server.

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

```js
// 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:

```js
// rollup.config.mjs

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

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

For convenience, a [Vite](https://vitejs.dev/)-friendly version of this plugin is also provided:

```js
// 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:

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

```js
module.exports = {
  transform: {
    '\\.(gql|graphql)$': 'graphql-mini-transforms/jest-simple',
  },
};
```

## Prior art

This loader takes heavy inspiration from the following projects:

- [`graphql-tag`](https://github.com/apollographql/graphql-tag) and [`graphql-persisted-document-loader`](https://github.com/leoasis/graphql-persisted-document-loader)
- [`graphql-loader`](https://github.com/samsarahq/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](https://www.npmjs.com/package/next-plugin-mini-graphql) - Provides [Next.js](https://nextjs.org/) support for `.graphql` files using `graphql-mini-transforms`

---
_Source: https://npm.io/package/graphql-mini-transforms · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._