or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-graphql-codegen--introspection

GraphQL Code Generator plugin for generating introspection JSON files from GraphQL schemas

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@graphql-codegen/introspection@4.0.x

To install, run

npx @tessl/cli install tessl/npm-graphql-codegen--introspection@4.0.0

index.mddocs/

GraphQL Code Generator Introspection Plugin

The @graphql-codegen/introspection plugin generates GraphQL introspection JSON files from GraphQL schemas. It provides comprehensive schema introspection capabilities with configurable options for minification, description inclusion, directive repeatability flags, schema descriptions, and specifiedByUrl fields.

Package Information

  • Package Name: @graphql-codegen/introspection
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @graphql-codegen/introspection

Core Imports

import { plugin, validate, IntrospectionPluginConfig } from "@graphql-codegen/introspection";

For CommonJS:

const { plugin, validate } = require("@graphql-codegen/introspection");

Basic Usage

The plugin is designed to be used with the GraphQL Code Generator CLI or programmatically:

import { plugin, IntrospectionPluginConfig } from "@graphql-codegen/introspection";
import { buildSchema } from "graphql";

// Create a GraphQL schema
const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

// Generate introspection JSON
const config: IntrospectionPluginConfig = {
  minify: false,
  descriptions: true
};

const introspectionJSON = await plugin(schema, [], config);
console.log(introspectionJSON); // Pretty-printed JSON string

With GraphQL Code Generator CLI configuration:

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'schema.graphql',
  generates: {
    'introspection.json': {
      plugins: ['introspection'],
      config: {
        minify: true,
        descriptions: false
      }
    }
  }
};

Architecture

The @graphql-codegen/introspection plugin is part of the GraphQL Code Generator ecosystem, a powerful toolkit for generating code from GraphQL schemas. This plugin operates within the GraphQL Code Generator's plugin architecture:

  • Plugin Framework: Built on the @graphql-codegen/plugin-helpers framework, utilizing standard plugin interfaces (PluginFunction, PluginValidateFn)
  • Schema Processing: Leverages GraphQL's native introspectionFromSchema function to generate comprehensive schema metadata
  • Federation Support: Integrates with federation detection to automatically clean Apollo Federation-specific types using removeFederation
  • Configuration Management: Uses @graphql-codegen/visitor-plugin-common utilities for consistent configuration handling across the GraphQL Code Generator ecosystem
  • Output Validation: Enforces JSON file output through built-in validation to ensure proper file format

The plugin operates as a pure transformation function, taking a GraphQL schema and configuration options as input and producing a JSON string representation of the schema's introspection data as output.

Capabilities

Plugin Function

Main plugin function that generates introspection JSON from a GraphQL schema.

/**
 * Main plugin function that generates introspection JSON from GraphQL schema
 * @param schema - GraphQL schema to introspect
 * @param _documents - Document files (unused by this plugin)
 * @param pluginConfig - Configuration options for the plugin
 * @returns Promise resolving to JSON string representation of schema introspection
 */
function plugin(
  schema: GraphQLSchema,
  _documents: any,
  pluginConfig: IntrospectionPluginConfig
): Promise<string>;

The plugin processes the GraphQL schema and returns a JSON string containing the complete introspection result. When federation is enabled, it automatically removes federation-specific types and directives before generating the introspection.

Validation Function

Validates plugin configuration and output file requirements.

/**
 * Validates plugin configuration and output file requirements
 * @param schema - GraphQL schema being processed
 * @param documents - Document files being processed
 * @param config - Plugin configuration
 * @param outputFile - Target output file path
 * @throws Error if output file extension is not .json
 */
function validate(
  schema: GraphQLSchema,
  documents: Types.DocumentFile[],
  config: any,
  outputFile: string
): Promise<void>;

This function ensures that the output file has a .json extension, throwing an error if the extension is incorrect.

Configuration Options

Complete configuration interface for customizing introspection output.

/**
 * Configuration options for the introspection plugin
 */
interface IntrospectionPluginConfig {
  /**
   * Set to true to minify the JSON output (removes whitespace and indentation)
   * @default false
   */
  minify?: boolean;

  /**
   * Whether to include descriptions in the introspection result
   * @default true
   */
  descriptions?: boolean;

  /**
   * Whether to include specifiedByUrl in the introspection result
   * @default undefined
   */
  specifiedByUrl?: boolean;

  /**
   * Whether to include isRepeatable flag on directives
   * @default true
   */
  directiveIsRepeatable?: boolean;

  /**
   * Whether to include description field on schema
   * @default undefined
   */
  schemaDescription?: boolean;

  /**
   * Internal flag for federation support - automatically removes federation types
   * @internal
   */
  federation?: boolean;
}

Types

// Re-exported from GraphQL
type GraphQLSchema = import('graphql').GraphQLSchema;

// Re-exported from @graphql-codegen/plugin-helpers
type PluginFunction<T> = import('@graphql-codegen/plugin-helpers').PluginFunction<T>;
type PluginValidateFn<T> = import('@graphql-codegen/plugin-helpers').PluginValidateFn<T>;
type Types = import('@graphql-codegen/plugin-helpers').Types;

Advanced Usage Examples

Minified Output

const minifiedConfig: IntrospectionPluginConfig = {
  minify: true,
  descriptions: false
};

const compactJSON = await plugin(schema, [], minifiedConfig);
// Returns minified JSON string without whitespace

Federation Schema Support

// When using with federated schemas, federation types are automatically removed
const federationConfig: IntrospectionPluginConfig = {
  federation: true,
  descriptions: true
};

const cleanIntrospection = await plugin(federatedSchema, [], federationConfig);
// Federation-specific types like _Entity, _Service are removed

Custom Schema Options

const fullConfig: IntrospectionPluginConfig = {
  descriptions: true,
  specifiedByUrl: true,
  directiveIsRepeatable: true,
  schemaDescription: true,
  minify: false
};

const detailedIntrospection = await plugin(schema, [], fullConfig);
// Includes all available metadata in the introspection result