Embedded GraphQL

GraphQL Analyzer provides full IDE support for GraphQL embedded in TypeScript, JavaScript, Vue, Svelte, and Astro files via tagged template literals.

Supported file types

File type	Extensions	How GraphQL is found
TypeScript / JavaScript	`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`	Tagged template literals (`gql`, `graphql`)
Vue	`.vue`	`<script>` / `<script setup>` blocks → tagged templates
Svelte	`.svelte`	`<script>` blocks → tagged templates
Astro	`.astro`	Frontmatter (`---`) section → tagged templates

All IDE features work inside embedded GraphQL regardless of file type:

Diagnostics at correct positions
Go to definition
Find references
Hover information

TypeScript / JavaScript

import { gql } from "graphql-tag";

const query = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
    }
  }
`;

Vue Single File Components

GraphQL is extracted from <script> and <script setup> blocks, including lang="ts" variants:

<script setup lang="ts">
import { gql } from "graphql-tag";

const query = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
    }
  }
`;
</script>

<template>
  <!-- ... -->
</template>

Svelte components

GraphQL is extracted from <script> blocks, including lang="ts" and context="module" variants:

<script lang="ts">
  import { gql } from "graphql-tag";

  const query = gql`
    query GetUser($id: ID!) {
      user(id: $id) { id name }
    }
  `;
</script>

Astro pages

GraphQL is extracted from the frontmatter section (between --- fences):

---
import { gql } from "graphql-tag";

const query = gql`
  query GetUser($id: ID!) {
    user(id: $id) { id name }
  }
`;
---

<html>
  <!-- ... -->
</html>

How it works

The analyzer extracts GraphQL from tagged template literals and maps positions between the source file and the extracted GraphQL. For Vue, Svelte, and Astro files, <script> blocks (or frontmatter) are first extracted, then processed through the same TypeScript/JavaScript pipeline. This means error positions, go-to-definition targets, and hover information all point to the correct location in your source file.

Configuring extraction

The extractConfig schema mirrors @graphql-tools/graphql-tag-pluck, so users coming from @graphql-eslint or any pluck-based pipeline can paste their pluck config directly. The pluckConfig key is also accepted as an alias.

By default, the tool recognizes gql and graphql as bare/global GraphQL tags, and tracks tags imported from graphql-tag, graphql-tag.macro, @apollo/client(/core), gatsby, the Relay packages, graphql.macro, and the urql/@urql/* family. Customize:

extensions:
  graphql-analyzer:
    extractConfig:
      modules:
        - "graphql-tag"
        - { name: "@apollo/client", identifier: "gql" }
        - { name: "custom-gql", identifier: "query" }
      globalGqlIdentifierName: ["gql", "graphql", "query"]

See Documents configuration for the full option list.

Magic comment extraction

In addition to tagged template literals, the analyzer extracts GraphQL from untagged string literals and template literals preceded by a /* graphql */ comment (matches gqlMagicComment, default "graphql"):

const query = /* graphql */ `
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
    }
  }
`;

const mutation = /* graphql */ `
  mutation UpdateUser($id: ID!, $name: String!) {
    updateUser(id: $id, name: $name) {
      id
    }
  }
`;

This covers patterns where the tag function is unavailable or unnecessary — the comment signals intent and triggers the same extraction pipeline as a recognized tag.

Common issues

GraphQL not detected in template literal?

The tag function must be imported from a recognized module:

// ✅ Works — gql from recognized module
import { gql } from "graphql-tag";

// ❌ Won't work — unknown module
import { gql } from "custom-unknown-module";

Add custom modules to extractConfig.modules in your config.

GraphQL not detected in Vue/Svelte/Astro files?

Make sure your documents glob includes the file extensions:

documents: "src/**/*.{graphql,ts,tsx,vue,svelte,astro}"