Introducing GraphQL Birdseye 🦅
We are proud to officially release graphql-birdseye! Birdseye allows you to view any GraphQL schema as a dynamic and interactive graph. Try it out on our demo site!
Birdseye uses a “fog of war” 🌁 navigation style which dynamically zooms to show a portion of the schema at a time. This significantly simplifies the process of finding related types when compared to displaying the entire schema at once.
Getting started
You can get started with birdseye by reading the instructions here. The library is currently available as a React component, but if we get requests for other frameworks like Angular or Vue, we would be happy to work on those as well 🙂.
Why we built it
We were inspired to make a GraphQL schema visualization tool that can you can add to other sites and packages. We have seen a couple of other excellent tools like graphql-rover, graphql-voyager and graphql editor. We originally planned to integrate voyager with graphql-playground, but it would have added 1.2 MB to the package. This bundle size made the library very difficult to integrate with any other tools.
To solve this problem we created Birdseye which is lightweight and works well with other tools. In this process, we also made some helpful changes to the user experience (📣 to Prisma for helping brainstorm the “fog of war” navigation).
How we built it
When we first started, we spent the first month trying out various diagramming libraries like WebCola, Cytoscape.js, dagre and many more. Some libraries supported a portion of the features while others supported a different subset. At this point, we considered building our own visualization library, and we quickly realized how crazy that would be 😅.
We decided to keep looking and finally came across JointJS 🎊. It gave us a nice API to be able to define custom shapes and provided excellent layout and link routing algorithms. It also gave us the ability to modify these algorithms according to our needs. Best of all, it added very little to the bundle size (~70kb).
Having settled on JointJS, the rest of the project focused on understanding the API in more detail and using it to build out the library. Some of the other tools we used to make this happen were:
- TypeScript: our go-to language whenever we can use it. The type-safety saves us from a lot of trouble by catching simple issues early on.
- Rollup: A bundler that specializes in packaging libraries.
- svg-pan-zoom: Simple pan/zoom solution for SVGs in HTML. It adds events listeners for mouse scroll, double-click, and pan.
Where we go from here
We are committed to improving this library and make it the go-to for visualizing your schema. We would love to hear your feedback so we can make it even better and we always welcome contributions. Some things we are planning to work on are:
- Improve performance for larger schemas
- Option to toggle zoom navigation style
- Smoother UI transitions and interactions
Tell us what you think 🤔
If you like Birdseye, please follow us on twitter (@novvumio) and give us a star 🌟 on GitHub! If you find any issues, we’d love to fix them! You can submit them here.
