View any GraphQL schema as a dynamic and interactive graph.
Try it out now: http://birdseye.novvum.io/
Description
Birdseye is an interactive tool that dynamically displays GraphQL schemas. It helps teams visualize and understand the nodes and connections within their schema. Birdseye was built using jointJS and makes for a lightweight addition to any web project.
Features
- Graphical view of any GraphQL schema
- Ability to click on a field or type to view its connections
- Dynamic zooming to focus on small portions of the schema at a time
- Add to any web project
- Customizable styling and theming
Javascript Library Documentation
This is the documentation to use Birdseye as a Javascript library. To learn how to use Birdseye as a React package, please refer to the React repository README.
Installation
Install using NPM or yarn
NPM
npm install --save graphql-birdseye-core
Yarn
yarn add graphql-birdseye-core
Usage
Here’s an example of how to use the Birdseye Javascript library in a React project. See the API Reference for how to pass your schema to the component.
;;// Instantiate the libraryconst birdseye = ; // define the data structureconst introspectionQuery = ; // get the introspection response from the schemaconst dataStructure = introspectionQuery__schema; // Initialize the librarybirdseye;
API
const birdseye = new GraphqlBirdseye({ theme })
Creates a Birdseye object.
Name | Type | Description |
---|---|---|
theme (optional) | object | An object defining the theme of the components. Theme objects should follow the type defined here. Here's a full example. |
init(el, bounds, dataStructure)
Initializes the Birdseye diagram with the GraphQL schema to display, the DOM element to attach it to, and its size.
Name | Type | Description |
---|---|---|
el |
HTML DOM Element | The HTML element on which to mount the Birdseye diagram. |
bounds |
object | The height and width of the diagram.width : Intheight : Int |
dataStructure |
BirdseyeDataStructure | The GraphQL schema to display, expressed as a Birdseye Data Structure. Read more about Birdseye Data Structures below. |
setDataStructure(newDataStructure)
Updates the GraphQL schema displayed in the Birdseye diagram.
Name | Type | Description |
---|---|---|
newDataStructure |
BirdseyeDataStructure | The GraphQL schema to display, expressed as a Birdseye Data Structure. Read more about Birdseye Data Structure below. |
setActiveType(activeType)
Changes the active type selected on the diagram. This function fires whenever a type is clicked, but it can also be used to change the active type manually.
Name | Type | Description |
---|---|---|
activeType |
String | The name value of the Type object from the Birdseye Data Structure. |
setSize(width, height)
Updates the width and height of the Birdseye diagram.
Name | Type | Description |
---|---|---|
width |
int | The width of the diagram. |
height |
int | The height of the diagram. |
on(event, callback)
Invokes a function when a type is clicked and the diagram is loading. It can invoke a function when the loading begins or when the loading ends.
Name | Type | Description |
---|---|---|
event |
String | Use either:"loading:start" "loading:stop" |
callback |
() => any | The function that will be invoked when the event triggers. |
BirdseyeDataStructure
Birdseye accepts GraphQL schemas defined in the Birdseye Data Structure. We chose to specify our own data structure because GraphQL schemas can be represented in various formats (i.e. introspection response, GraphQL Schema Object, etc.). Birdseye ships with two translators to create Birdseye Data Structures.
introspectionConverter
: Converts the response of an introspection query into a Birdseye Data Structure. Use the response from this introspection query with this converter.schemaConverter
: Converts a GraphQL Schema Object into a Birdseye Data Structure. You can use the ExecutableSchema from GraphQL tools to create a GrapahQL Schema Object.
Roadmap
We have plans to keep improving Birdseye. Here's what is next:
- Improve performance for larger schemas
- Option to toggle zoom navigation style
- Smoother UI transitions and interactions
Contributing
This is an open source project. To learn how to contribute, please check out our contributing guide.
License
MIT © Novvum
Made with ❤️ by Novvum