GitHub engineer Gregor Martynus recently described his journey to refactor the GitHub official REST JavaScript SDK, originally containing about 16 thousand lines of code across six files total, into a more maintainable and modular project.
As Martynus explains,
The library’s core piece was a huge routes.json file with nearly eight thousand LOC, and it was supposed to define all of GitHub’s REST API endpoints.
The routes.json file was managed manually, which made the task of adding missing endpoints or fixing existing definitions particularly hard. The first step Martynus took was to write a script that scraped GitHub’s REST API documentation and generated a JSON representation of the API. If the generated routes changed, the script sends a pull request with the changes and a new release is released automatically, including full TypeScript definitions. This approach guarantees the GitHub REST endpoints are always up-to-date and complete in the JavaScript SDK without major effort.
Next, Martynus started working on modularity, aiming to benefit browser-based and other lightweight clients by enabling them to load only the features they actually need.
Instead of a single, monolithic library which implements all REST API endpoints, authentication strategies, and recommended best practices (such as pagination), it’s important to give users the choice to use lower-level libraries. That way users can make their own choices about trade-offs between bundle size and features.
This effort led to the following architecture, with lower-numbered layers sitting closer to the API surface:
Martynus took this rearchitecture as a chance to get rid of deprecated code and started afresh with a new core package to provide the foundation for all other OctoKit modules. Hooks played a critical role enabling to split independent features across distinct plugin, for example authentication strategies, pagination, and so on. Furthermore, the use of TypeScript allowed Martynus to get rid of most validation code, since checks were carried through at compile time.
While Martynus article's title might lead you into thinking he really managed to shrink almost 50k lines of code into ten, this is not actually the case. In fact, most code originally belonging to the JavaScript SDK did not disappear and was shifted to separate modules. That does not mean that he did not manage to achieve his goals of making the SDK more maintainable and modular—quite the opposite, indeed. If you are interested in the full details, do not miss his original post.
