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.
Top comments (12)
This is very nice, but shouldn't it be integrated on the GQL server-layer, rather than in the react client?
I would expect this to be valuable where the API is, i.e. for developers trying to access and utilise your GraphQL service, you would offer an extra RESTful endpoint on that API (e.g. in Expres, Koa, or whatever you're using) that brings up this schema explorer, so they know what to develop against.
But if I understand correctly, you're expecting people to add this to their existing (React) client apps instead?
👋 Hi Patrick! The guy who built Birdseye here 😃.
Our intention with Birdseye is to make it compatible with other GraphQL tools like GraphiQL and GraphQL playground. We felt that releasing it as a react component made it more portable for other members of the community to integrate into their own projects. We are planning to make PRs to some of these libraries integrating Birdseye.
We also published a pure JavaScript version called graphql-birdseye-core (documentation coming soon) which can be used in even more places like a Vue, Angular, or even as a standalone endpoint via Express, etc.
Ah, that makes sense. Certainly the core version could then already be used for server-side integration. Thanks for clarifying!
If you are willing to contribute a server-side version, I think the community would really benefit from it! 🙂
a Vue or standalone version would be great
Hi Joe!
We will definitely get working on this. We would also be grateful if you submitted a PR 🙏.
We published a pure JavaScript version called graphql-birdseye-core (documentation coming soon) which can be used to build a Vue, Angular, or standalone endpoint via Express, etc.
In the meantime, I'll go ahead and submit an issue on the repo so we can keep track of it 🙂.
^ +1
This is freaking awesome, love your work guys!
thanks!!
Awesome, thanks for sharing!
Seems awesome, but after loading our schema, my 2017 i5 MBP with nothing else running immediately locks up and uses 100+% cpu. Hope you guys get some efficiency going soon!
Hey Andrew! We have seen some performance issues with massive schemas. We are looking into ways to optimize for that. Can you share any stats on how large your schema is?