GraphQL Explorer Component for React

This repository contains an open-source GraphQL Explorer Component for React, enabling developers to easily integrate an interactive GraphQL playground into their React applications.

Features

The GraphQL Explorer is designed with developers in mind, offering features that simplify workflows and enhance productivity. Here’s what it includes:

• Query Builder: Construct complex GraphQL queries with an easy-to-use interface.
• History: Quickly access and reuse previous queries.
• Saved Collections: Keep your frequently used queries organized and ready.
• Define Extension Headers: Customize and add extension headers to your GraphQL requests for advanced use cases.
• Share Queries: Share queries with others, whether or not they include variables.
• Multi-Tab Support: Work on multiple queries simultaneously for better multitasking.
• Run 10x Options: Send multiple queries at once to test performance and scalability.
• Response Viewer with Headers: Debug effectively with detailed response and header insights.
• Schema Viewer: Navigate and explore your schema with a visual overview.
• PreFlight Scripts: Set up login or other pre-configurations before running queries.
• Local Preferences: Save and retrieve user preferences, such as layout and active tabs.

---

Installation

Install the package via npm or yarn:

npm install @inigolabs/graphql-explorer

or

yarn add @inigolabs/graphql-explorer

---

Usage

Import the Explorer component and include it in your application. The defaultState prop is required to initialize the explorer.

import "@inigolabs/graphql-explorer/styles";
import Explorer from "@inigolabs/graphql-explorer";

function App() {
  const defaultState = {};

  return (
    <div>
      <Explorer
        defaultState={defaultState}
        onStateChange={(state) => console.log("Explorer state updated:", state)}
      />
    </div>
  );
}

---

API

Props

Prop	Type	Required	Description
theme	"light" | "dark"	No	Sets the theme for the explorer interface.
access	"admin" | "user"	No	Specifies the access level of the current user.
defaultState	ExplorerState	Yes	Initial state for the explorer, including tabs, collections, and layout preferences.
onStateChange	(state: ExplorerState) => void	No	Callback triggered when the state of the explorer changes.

---

ExplorerState Description

The ExplorerState object represents the state of the GraphQL Explorer, which is essential for initializing and managing the component's behavior.

Structure

Key	Type	Description
url	string	The base URL for the GraphQL endpoint.
collections	ExplorerCollection[]	Saved collections of reusable queries and their variables.
history	ExplorerTabHistoryItem[]	History of previously executed queries.
headers	string	JSON string representing custom headers for GraphQL requests.
envVariables	string	JSON string of environment variables used during queries.
preflightScript	string	Script executed before sending requests, useful for custom logic.
preflightEnabled	boolean	Flag indicating if the preflight script is enabled.
tabs	ExplorerTab[]	Array of tabs representing open queries in the explorer.
activeTabId	string	The ID of the currently active tab.
proxyEnabled	boolean	Flag indicating if a proxy is enabled for requests.
historyEnabled	boolean	Flag indicating if query history is enabled.
layout	{ tab?: [number, number]; request?: [number, number] }	Layout configuration for the explorer's UI components, such as tab and request panels.

---

Children Types

ExplorerCollection

Represents a collection of saved queries.

Key	Type	Description
id	string	Unique identifier for the collection.
name	string	Name of the collection.
operations	ExplorerCollectionOperation[]	List of operations (queries) in the collection.

---

ExplorerCollectionOperation

Represents an operation (query) within a collection.

Key	Type	Description
name	string	Name of the operation.
query	string	GraphQL query string.
variables	string	JSON string of query variables.

---

ExplorerTab

Represents a tab in the explorer.

Key	Type	Description
id	string	Unique identifier for the tab.
query	string	The GraphQL query in the tab.
variables	string	JSON string of variables associated with the query.
response	ExplorerTabInfoResponse	The response data for the query.
doc	ReturnType<typeof parse>	Parsed GraphQL document from the query.

---

ExplorerTabHistoryItem

Extends ExplorerTab with additional metadata for history entries.

Key	Type	Description
operationName	string	The name of the operation in the history.
createdAt	string	Timestamp when the history entry was created.

---

ExplorerTabInfoResponse

Represents the response information for a tab's query.

Key	Type	Description
data	any	The response data from the query.
headers	any	Headers returned from the response.
status	number	HTTP status code of the response.
size	number	Size of the response data in bytes.
time	number	Time taken for the request in milliseconds.

---

Contribution

We welcome contributions to enhance this component. Please follow these steps:

1. Fork the repository.
2. Install dependencies: npm install
3. Start the development server: npm run dev
4. Create a new branch: git checkout -b feature-name.
5. Commit your changes: git commit -m 'Add feature'.
6. Push the branch: git push origin feature-name.
7. Submit a pull request.

FAQ

• To run the Expoler on Next JS, disable server side rendering.
• create-react-app is deprecated and no longer supported.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.