babel-plugin-import-graphql

2.8.1 verified Sat Apr 25 auth: no javascript

A Babel plugin (v2.8.1) that enables importing .graphql and .gql files directly in JavaScript/TypeScript code, converting them into GraphQL AST objects via graphql-tag. Supports schema files with #import syntax, operation/fragment files with all import variants, and emits .d.ts declarations. Requires graphql >=0.9.6 and graphql-tag >=2.1.0 as peer dependencies. Commonly used in Apollo projects to avoid string literals and manual parsing. Active but with infrequent updates (last release January 2021).

Common errors

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause Webpack is trying to parse .graphql file without the babel plugin active.

fix

Add 'import-graphql' to Babel plugins in your webpack config (typically via .babelrc or babel.config.js).

error Cannot find module 'graphql-tag' ↓

cause Missing peer dependency 'graphql-tag' when using runtime option.

fix

Install graphql-tag: npm install graphql-tag

error TypeError: Cannot read properties of undefined (reading 'kind') ↓

cause Using an outdated version or incorrect import syntax for the GraphQL AST.

fix

Ensure you are importing the default export from the .graphql file, not a named export unless the plugin does not support named exports for that file type.

error Babel 7: .babelrc ignores plugins? ↓

cause Babel 7 requires @babel/core; the plugin may not be properly added to the Babel config.

fix

Use 'plugins': ['import-graphql'] in babel.config.js or .babelrc; ensure @babel/core is installed.

Warnings

gotcha Cache must be manually cleared after editing .graphql files: node_modules/.cache/babel-loader must be deleted. ↓

fix Prepend your start script with 'rm -rf ./node_modules/.cache/babel-loader' or use --reset-cache for React Native.

deprecated Old package name 'babel-plugin-inline-import-graphql-ast' is deprecated. The current package is 'babel-plugin-import-graphraphql'. ↓

fix Replace 'babel-plugin-inline-import-graphql-ast' with 'babel-plugin-import-graphql' in package.json and Babel config; minimum version 2.4.4.

gotcha Windows users cannot use 'rm -rf' to clear babel cache. ↓

fix Use 'rimraf' or another cross-platform command to delete node_modules/.cache/babel-loader.

breaking Removed dependence on require.resolve to fix issues with Node v12. ↓

fix Upgrade to v2.8.0 or later for Node v12+ compatibility.

gotcha #import syntax in schema files cannot import specific types; entire file content is imported. ↓

fix Store each type in a separate file if selective imports are needed.

Install

npm install babel-plugin-import-graphql

yarn add babel-plugin-import-graphql

pnpm add babel-plugin-import-graphql

Imports

default import from .graphql/.gql
wrong
```
const myQuery = require('./query.graphql').default
```
correct
```
import myQuery from './query.graphql'
```
The plugin transforms .graphql imports into AST objects. Using require may not work correctly if the plugin is configured for Babel.
named import from .graphql/.gql
wrong
```
import myQuery from './queries.graphql'
```
correct
```
import { myQuery } from './queries.graphql'
```
Named exports are supported for schema files that contain multiple operations; default import returns the entire parsed document.
namespace import from .graphql/.gql
wrong
```
import queries from './queries.graphql'
```
correct
```
import * as queries from './queries.graphql'
```
Namespace imports are supported since v2.8.0; each named export becomes a property of the namespace object.

Quickstart

Shows basic setup: Babel plugin configuration, a GraphQL query file, and import/use in a React Apollo component.

// .babelrc
{
  "plugins": ["import-graphraphql"]
}

// query.graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

// index.js
import getUserQuery from './query.graphql'
import { useQuery } from '@apollo/client'

function UserProfile({ userId }) {
  const { data } = useQuery(getUserQuery, { variables: { id: userId } })
  return <div>{data?.user?.name}</div>
}