DOCSEARCHbyAlgolia
Submit Docs

GraphiQL

repository·main·Indexed 12 days ago

https://github.com/graphql/graphiql

The official GraphQL IDE and a suite of language services, editor integrations (CodeMirror, Monaco, VS Code), and CLI tools designed to provide schema-aware GraphQL development experiences.

Tokens
78.8K
Snippets
242
Records
345
Agent score
97%

What's inside GraphiQL

  1. Overview of the GraphQL IDE Monorepo

    main

    The GraphQL IDE monorepo provides a suite of tools for building, extending, or using GraphQL development environments. It includes an official language service, LSP servers, CLI tools, and editor integrations for CodeMirror and Monaco.

    Key components include:

    • GraphiQL: The reference in-browser GraphQL IDE.
    • Language Services: Core logic for schema-driven GraphQL intelligence via graphql-language-service.
    • Editor Modes: Specialized language modes for CodeMirror (v5 and v6) and Monaco.
    • IDE Extensions: Support for Visual Studio Code via LSP and syntax highlighting extensions.
    • CLI & Server: Tools to run the language service as a standalone server or via command line.

  2. Overview of graphql-language-service-server

    main

    The graphql-language-service-server is a server process that backs the GraphQL Language Service. It provides an interface for building GraphQL language services specifically designed for IDEs. It currently offers partial support for Microsoft's Language Server Protocol (LSP).

    Key supported features include:

    • Diagnostics: Spec-compliant GraphQL syntax linting and validations.
    • Autocomplete: Spec-compliant suggestions.
    • Hyperlinks: Spec-compliant support for navigating to fragment definitions and named types (type, input, enum).
    • Outline View: Support for viewing the structure of queries.
    • Template Tag Support: Support for gql, graphql, and other template tags within JavaScript, TypeScript, JSX, TS, Vue, and Svelte files, with an interface available for custom file parsing.

  3. Overview of @graphiql/toolkit

    main

    The @graphiql/toolkit library is a general-purpose utility library designed for building GraphQL IDEs. It serves as a foundational layer for other packages in the monorepo, such as graphiql and @graphiql/react, and provides essential utilities for developers working with those packages.

    Key capabilities include utilities for managing data fetching in GraphQL environments.

  4. Overview of GraphQL Syntax Support

    main

    The vscode-graphql-syntax package provides full GraphQL syntax highlighting and language support features like bracket matching within VS Code. It is designed to work even if you do not use graphql-config, and it can be used alongside other extensions besides vscode-graphql.

    Supported file types and contexts include:

    • Direct GraphQL files: .graphql, .gql, and .graphqls
    • Embedded in other languages:
      • Javascript, Typescript, and JSX/TSX
      • Vue (SFC components)
      • Svelte
      • ReasonML/ReScript (via %graphql())
      • Python
      • PHP
      • Markdown (within code blocks)
      • Scala

  5. Overview of graphql-language-service

    main

    The graphql-language-service package aggregates the necessary dependencies to build web or desktop IDE services for the GraphQL language. It provides the core logic required to implement Language Server Protocol (LSP) compliant services, making it suitable for IDE plugins, browser-based applications, or desktop applications.

    Note: This package is considered mostly experimental, though it relies heavily on stable libraries. As of version 3.0.0, the LSP Server command line interface has been moved to the graphql-language-service-cli package.

  6. Participate in the GraphiQL & GraphQL LSP Working Group

    main

    The GraphiQL and GraphQL LSP Working Group focuses on proposals and specifications for plugin interfaces, developer-facing interfaces, and overall feature lifecycles. The group covers the entire monorepo, including:

    • GraphiQL and its plugins
    • codemirror-graphql
    • The new Monaco mode
    • The LSP service interface, LSP server, and LSP server CLI

    To participate in decision-making and feature proposals, you can join the monthly meetings or engage via Discord and GitHub.

  8. Execute GraphQL operations inline with `graphql.vscode-graphql-execution`

    main

    The graphql.vscode-graphql-execution extension allows you to run GraphQL operations directly within your code editor. It supports the following file types:

    • .ts / .tsx
    • .js / .jsx
    • .graphql, .gql, or .graphqls files

    Workflow:

    1. A CodeLens appears above your GraphQL operations. Click it to start execution.
    2. If your operation requires variables, a dialog will prompt you to enter them.
    3. The execution results or network errors will be displayed inline.

  9. Use @graphiql/plugin-history to persist executed requests

    main

    The @graphiql/plugin-history package provides hooks to manage and persist the history of executed GraphQL requests within a GraphiQL instance. It allows users to keep track of previous queries and mutations using local storage.

    Key APIs:

    • useHistory: A hook that handles the persistence of executed requests in storage.
    • useHistoryActions: A hook that provides actions to interact with the history (e.g., clearing or managing entries).

  10. Customize GraphQL Language Service features via extensions

    main

    You can extend the language service behavior by adding a languageService object inside the extensions field of your GraphQL configuration.

    Supported features:

    • customDirectives: Array of strings to append to the schema.
    • customValidationRules: A function returning an array of GraphQL validation rules.
    • schemaCacheTTL: Integer (ms) to adjust schema cache lifetime (default 30s). Lower this for active development.
    • languageService.cacheSchemaFileForLookup: Boolean. Enables/disables generating SDL files for definition lookup.
    • languageService.enableValidation: Boolean. Enables/disables validation (set to false if using graphql-eslint).
    • languageService.fillLeafsOnComplete: (Experimental) Enhanced auto-expansion of leaf fields.
    • languageService.locateCommand: Function to override definition peek/jump results (e.g., for Relay-style pathing).
    module.exports = {
  extensions: {
    customDirectives: ['@myExampleDirective'],
    customValidationRules: require('./config/customValidationRules'),
    schemaCacheTTL: 1000,
    languageService: {
      cacheSchemaFileForLookup: true,
      enableValidation: true,
      fillLeafsOnComplete: true,
      locateCommand(projectName, typePath, info) {
        // ... implementation
        return { uri: path, range };
      },
    },
  },
};

  11. How GraphiQL manages state and plugins

    main

    GraphiQL is transitioning from a legacy React architecture (using this.setState) to a modern architecture based on useReducer and React Context. This shift is designed to facilitate a plugin system where state and event handlers can be shared across plugins without prop-drilling.

    Key architectural principles for the new version include:

    • State Management: Complex state is managed via useReducer within a GraphiQLSessionProvider.
    • Abstraction via Hooks: Instead of exposing raw state or reducers directly to plugins (which would create a brittle API), the architecture favors exposing hooks and selectors. This allows the internal state structure to change without breaking downstream plugins.
    • Plugin Integration: Plugins can leverage the ThemeProvider (using theme-ui) to ensure their UI components (like tabs or views) automatically match the user's theme.
    • Performance: To prevent performance degradation from frequent re-renders or heavy computations, the architecture emphasizes:
      • Using selectors instead of raw state.
      • Debouncing AST (Abstract Syntax Tree) generation (e.g., using background workers or idle callbacks).
      • Ensuring onChange callbacks provide both text and cursor position.

  12. Customize the theme using CSS variables

    main

    Customization of @graphiql/react components is achieved through CSS variables.

    Colors

    Colors are defined using the HSL format. Instead of a single color value, the CSS variables contain the three components (hue, saturation, and lightness). This allows the library to use the hsla() function to apply transparency while maintaining consistent contrast across different backgrounds.

    All available customization variables are defined in the root.css file within the package.