@sucoza/graphql-devtools-plugin

GraphQL DevTools Plugin

A comprehensive GraphQL DevTools plugin for TanStack DevTools that provides advanced schema exploration, visual query building, operation monitoring, and performance analytics.

Features

🔍 Schema Explorer

• Interactive Schema Browser: Navigate through GraphQL types, queries, mutations, and subscriptions
• Type Details: View field descriptions, arguments, deprecation status, and relationships
• Schema Statistics: Overview of type counts, operations, and schema health
• Auto-Introspection: Automatically detect and introspect GraphQL endpoints

🛠️ Visual Query Builder

• Drag & Drop Interface: Build queries visually by selecting fields and configuring arguments
• Variable Management: Define and manage query variables with type validation
• Real-time Validation: Instant feedback on query syntax and schema compliance
• Query Generation: Automatically generate optimized GraphQL queries
• Query Execution: Execute queries directly from the builder

📊 Operation History

• Complete Operation Tracking: Monitor all GraphQL queries, mutations, and subscriptions
• Detailed Operation View: Inspect query, variables, response, and network information
• Performance Metrics: Track execution times, success rates, and error patterns
• Operation Replay: Re-execute previous operations for testing
• Advanced Filtering: Filter by operation type, status, time range, and search terms

📈 Performance Monitoring

• Execution Time Tracking: Monitor query performance and identify bottlenecks
• Success Rate Analytics: Track success/failure rates across operations
• Error Analysis: Categorize and analyze GraphQL errors
• Performance Trends: Visualize performance metrics over time

🔧 Developer Experience

• Network Interception: Automatically detect and capture GraphQL operations
• Export/Import: Export operation history and schema information
• Dark Mode Support: Full dark/light theme support
• Responsive Design: Works on all screen sizes
• TypeScript Support: Fully typed with comprehensive TypeScript definitions

Installation

npm install @sucoza/graphql-devtools-plugin

Quick Start

Basic Setup

import { GraphQLDevToolsPanel, createGraphQLDevToolsClient } from '@sucoza/graphql-devtools-plugin';

// Create the DevTools client
const graphqlDevToolsClient = createGraphQLDevToolsClient();

// Add to your app
function App() {
  return (
    <div>
      {/* Your app content */}
      
      {/* DevTools panel */}
      <GraphQLDevToolsPanel />
    </div>
  );
}

With TanStack DevTools

import { TanStackDevtools } from '@tanstack/react-devtools';
import { GraphQLDevToolsPanel } from '@sucoza/graphql-devtools-plugin';

function App() {
  return (
    <div>
      {/* Your app content */}
      
      <TanStackDevtools>
        <GraphQLDevToolsPanel />
      </TanStackDevtools>
    </div>
  );
}

Configuration

Schema Introspection

Configure endpoints for automatic schema introspection:

import { createGraphQLDevToolsClient } from '@sucoza/graphql-devtools-plugin';

const client = createGraphQLDevToolsClient();

// Add GraphQL endpoints
const schemaManager = client.getSchemaManager();
schemaManager.updateOptions({
  endpoints: ['http://localhost:4000/graphql', '/api/graphql'],
  autoIntrospect: true,
  cacheTimeout: 300000 // 5 minutes
});

Custom Headers

Add custom headers for authenticated endpoints:

// Introspect with custom headers
await client.introspectSchema('http://localhost:4000/graphql', {
  'Authorization': 'Bearer your-token',
  'X-Custom-Header': 'value'
});

Network Interception

The plugin automatically intercepts GraphQL requests. Configure interception options:

const interceptor = client.getInterceptor();

interceptor.updateOptions({
  enabled: true,
  endpoints: ['/graphql', '/api/graphql'],
  autoDetectEndpoints: true,
  maxOperationHistory: 1000
});

API Reference

GraphQLDevToolsClient

const client = createGraphQLDevToolsClient();

// Schema operations
await client.introspectSchema(endpoint, headers);
client.getSchemaManager();

// Query builder
client.setQueryBuilderOperationType('query' | 'mutation' | 'subscription');
client.addQueryBuilderField(field);
client.generateQuery();
client.validateQueryBuilder();

// Operation management
client.clearOperations();
client.getFilteredOperations();
client.exportOperations();

// UI controls
client.selectTab('operations' | 'schema' | 'query-builder' | 'performance');
client.toggleRecording();
client.updateFilters(filters);

React Hooks

import { useGraphQLDevToolsStore } from '@sucoza/graphql-devtools-plugin';

function CustomComponent() {
  const state = useGraphQLDevToolsStore();
  
  return (
    <div>
      <p>Total operations: {state.operations.length}</p>
      <p>Schema loaded: {state.schema.schema ? 'Yes' : 'No'}</p>
    </div>
  );
}

Example Application

The example/ directory contains a full demo application showing all features:

cd example
npm install
npm run dev

The example includes:

• Mock GraphQL server with sample schema
• Sample queries and mutations
• Interactive demo interface
• DevTools panel integration

Development

Building

npm run build

Testing

npm test
npm run test:ui

Development Mode

npm run dev

Type Checking

npm run typecheck

Schema Requirements

The plugin works best with GraphQL schemas that support introspection. Ensure your GraphQL server has introspection enabled:

// Apollo Server example
const server = new ApolloServer({
  typeDefs,
  resolvers,
  introspection: true,  // Enable introspection
  playground: true      // Optional: enable GraphQL Playground
});

Browser Support

• Chrome 88+
• Firefox 85+
• Safari 14+
• Edge 88+

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests
• Submit a pull request

License

MIT

Part of the @sucoza TanStack DevTools ecosystem.

Changelog

v1.0.0

• Initial release
• Schema exploration and introspection
• Visual query builder
• Operation history and monitoring
• Performance analytics
• Network interception
• Export/import functionality