GraphQL Doc Scope

A beautiful, interactive React library for exploring GraphQL schemas. Built with TypeScript, Framer Motion, and Shiki for a delightful developer experience.

✨ Features

• 🎨 Beautiful UI - Modern, clean design with smooth animations
• 🌓 Dark/Light Mode - Built-in theme support with customizable colors
• 🔍 Interactive Exploration - Hover to preview types, click to add them to the view
• 📦 Type Safe - Built with TypeScript for full type safety
• 🎭 Smooth Animations - Powered by Framer Motion for buttery transitions
• 💅 Syntax Highlighting - VSCode-quality highlighting with Shiki
• 🎯 Smart Deduplication - Never shows the same type twice
• 🪶 Lightweight - Minimal dependencies, optimized bundle size

📦 Installation

npm install graphql-doc-scope
# or
pnpm add graphql-doc-scope
# or
yarn add graphql-doc-scope

🚀 Quick Start

import { GraphQLDocScope } from 'graphql-doc-scope';
import type { IntrospectionResult } from 'graphql-doc-scope';

// Your GraphQL introspection schema
const schema: IntrospectionResult = {
  __schema: {
    // ... introspection data
  }
};

// Get a field or type to start from
const queryType = schema.__schema.queryType;
const fields = schema.__schema.types.find(t => t.name === 'Query')?.fields || [];
const targetField = fields[0];

function App() {
  return (
    <GraphQLDocScope
      schema={schema}
      target={targetField}
      colorMode="light"
    />
  );
}

📖 API

Props

GraphQLDocScope

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | schema | IntrospectionResult | Yes | - | GraphQL introspection schema JSON | | target | Type \| Field | Yes | - | Initial type or field to display | | colorMode | 'light' \| 'dark' | No | 'light' | Color theme mode | | theme | Partial<Theme> | No | - | Custom theme colors | | className | string | No | '' | Additional CSS class names | | style | React.CSSProperties | No | {} | Inline styles |

Types

interface IntrospectionResult {
  __schema: Schema;
}

interface Theme {
  light: ThemeColors;
  dark: ThemeColors;
}

interface ThemeColors {
  background: string;
  text: string;
  accent: string;
  border: string;
  hover: string;
  preview: string;
}

🎨 Theming

GraphQL Doc Scope comes with beautiful default themes for both light and dark modes. You can customize them:

<GraphQLDocScope
  schema={schema}
  target={targetField}
  colorMode="dark"
  theme={{
    dark: {
      background: '#1a1a1a',
      text: '#f5f5f5',
      accent: '#00ff88',
      border: '#333',
      hover: '#2a2a2a',
      preview: '#252525',
    }
  }}
/>

🎯 How It Works

1. Initialize - Start with a Query, Mutation, or Subscription field
2. View - The component shows the field in its parent type context with beautiful syntax highlighting
3. Discover - Type references in the code have dotted underlines indicating they're interactive
4. Hover - Hover over an underlined type name to see a preview of its definition appear below
5. Click - Click on the type name to permanently add its definition to the view
6. Explore - Continue clicking on referenced types to explore deeper into the schema
7. Deduplicate - Each type is only displayed once; already-displayed types aren't interactive

Interactive Features

• Dotted underline on type references that can be explored
• Solid underline + color change on hover
• Preview appears below the block you're hovering on (not as overlay)
• Smooth animations when adding new types
• Smart filtering - types already in view aren't shown as clickable

🔧 Development

Setup

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build library
pnpm build:lib

# Build example app
pnpm build

Project Structure

graphql-docs-scope/
├── src/
│   ├── lib/           # Library source code
│   │   ├── GraphQLDocScope.tsx
│   │   ├── SchemaParser.ts
│   │   ├── CodeGenerator.ts
│   │   ├── types.ts
│   │   ├── theme.ts
│   │   └── index.ts
│   └── example/       # Example application
│       ├── App.tsx
│       ├── main.tsx
│       └── index.css
├── latest.json        # Example schema
└── package.json

🏗️ Built With

• React - UI framework
• TypeScript - Type safety
• Framer Motion - Animations
• Shiki - Syntax highlighting
• Vite - Build tool

📝 License

MIT © [Your Name]

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

💡 Use Cases

• API Documentation - Beautiful, interactive API docs
• Developer Tools - Schema exploration in dev tools
• Education - Teaching GraphQL schema design
• Debugging - Understanding complex schema relationships

🌟 Why GraphQL Doc Scope?

Most GraphQL schemas grow large and complex quickly. Traditional documentation is static and hard to navigate. GraphQL Doc Scope makes exploration interactive and intuitive, letting you discover types naturally as you explore your schema from the inside out.

Made with ❤️ for the GraphQL community