Back in March 2021, Anvil released SpectaQL to the open source community with the goal of becoming the de-facto, go-to library to use for auto-generating static HTML documentation for any GraphQL API. We continue to be very pleased with the progress we've made:
- It gets downloaded roughly 18,000 times per week on NPM
- It has over 750 stars on Github
- It is commonly ranked 1st among GraphQL documentation generators
- It has a healthy amount of user support and Github issue activity
- It continues to evolve with new features and with the JavaScript ecosystem
The release of SpectaQL 1.0 back in April 2022 was a major milestone. Many improvements—both internal and external—were made, and it set up SpectaQL for long term success. Since then, SpectaQL has continued to evolve and improve in that major version. At the same time, a number of features and changes that we wanted to make would have required a "breaking change", so they had to be put aside for a "major" release. We recently felt that the time had come to bite the bullet and make another big release.
In the rest of this article, I'm going to outline some of the major changes, enhancements, and new features, as well as the decision process around some of the things we've done. I hope you find it informative and interesting.
Forging ahead
The Node.js ecosystem continues to evolve at a breakneck pace. The current LTS version is 18, with Node 20 coming up fast next year in 2023. Many projects have moved towards ensuring that they work on and embrace the latest versions of Node, and we've decided to do the same thing with SpectaQL. SpectaQL now supports Node 18, and we'll be adding support for for Node 20 in due time as becomes current.
Breaking from the past
While it's important to embrace the future, it's sometimes not possible without letting go of the past. This is the case with SpectaQL as well. Many dependencies used by SpectaQL had dropped support for versions of Node that SpectaQL was still supporting, specifically Node 12. This kept us from being able to update many of our dependencies, so things started to get outdated and certain features could not be implemented. SpectaQL version 2.0 drops support for Node 12, which went End Of Life earlier in 2022.
One big benefit of supporting Node >= 14 was that it now allowed us to use ESM / .mjs modules. Many active packages in the NPM ecosystem are going the module route, and now SpectaQL will be ready to upgrade to them when they do.
This also has the added benefit of being able to support modules in any custom themes developed by users without the need for transpilation to CommonJS. This is a huge win for those who've already gone all-in to writing in ESM.
Security & Privacy
SpectaQL was born from work done in other open source projects, and as a result its roots run deep. SpectaQL still uses Grunt as its task runner under the hood. And while Grunt itself is actively maintained, many of the plugins for it that are used by SpectaQL have been abandoned. One of the problems there is that when the occasional security vulnerability is discovered in one of those plugins or its dependencies, there is not going to be an update to patch that vulnerability. Prior to SpectaQL 2.0, an npm audit would result in myriad vulnerabilities. This is not good, and our users noticed.
Starting with version 2.0, SpectaQL has taken some of the unmaintained plugins and moved them "in house" into the codebase. We then took the time to update their dependencies, fix any problems, and ensure that there are zero vulnerabilities. While this was a complicated endeavor to get set up, it will pay dividends over time by keeping our users safe from vulnerabilities, and patching any vulnerabilities more quickly.
The default theme included with SpectaQL 1.0 included some CSS that loaded an external font from a 3rd party site. Although unintentional and low risk, some users did point out that technically this could be considered an issue with GDPR in some areas of the world. When this was brought to light, we immediately implemented a way to disable this behavior in 1.0, but now in 2.0 we have removed the 3rd party font loading altogether.
Some other notable changes
- The configuration YAML files may now contain environment variables which will be expanded.
- If you're using the API, the
runandloadDatamethods are now asynchronous and return a promise. - The default theme now lists any Subscriptions just after Queries and Mutations instead of way at the bottom.
- The default theme now has improved accessibility support.
- Many more options that were CLI only can now be specified in the config YAML.
- Revamped and expanded matrix testing in Github Actions.
Checkout the CHANGELOG for a more complete list of changes.
What remains
While we've gone to painstaking lengths to modernize the library, limited time and resources naturally result in some things getting put off for "later". Here are a few things that we'll be looking to address in upcoming versions:
- Eventually dropping Grunt as a requirement and replacing it with another task runner or some internal solution.
- Adding the ability to generate executable code or curl examples for queries or mutations.
- Pagination for large schemas.
- ...a whole lot more of things that users have asked for.
Summary
SpectaQL still owes a great deal to its original DNA, but we are continuing to modernize, improve and prepare it for the future of the Node ecosystem. Security, compatibility and of course functionality will continue to be huge focuses for the project, and are served well by the changes that we rolled out in version 2.0. This is another big step forward for the future of SpectaQL and we hope that the community continues to embrace and develop with it.
Enjoy!