A few months ago, I was asked to make some changes in TravelgateX's API GraphQL schema. After making the changes and installing our API in the production environment, I started thinking of ways that these GraphQL schema changes can be made more efficiently and using a mix of different tools and technologies that our company uses. A collegue of mine suggested that the schema can be loaded in a Github repository and then, once the application is started, it can be fetched and loaded as the current versión of the GraphQL schema used by the API.
I don’t know about you but when someone suggests an idea I find intriguing, I’m the type of person that just becomes obsessed of making the dream a reality. And so I did! In the following article I’m going to show you how to build an server in NodeJS that recovers the API GraphQL schema it uses from a Git repository. I’m going to explain the different parts of the project and in the end show the final result.
Prerequisits
- NodeJS (version 18.0 or above) installed.
- An active Git account and Git installed in your machine.
- Preferably an IDE like VS Code where you can run and debug your code.
Fetching the GraphQL Schema from Git
The schema fetch is relatively easy. We are going to use the git commands you probably already know (git pull, git clone, etc) launching them from our main application when we start the server. To do this we will have to launch an internal child process (another thread) that will launch these git commands. For this purpose we will use the following node module:
Now we will build a js function that will validate if the current repo is already cloned from Git. If it’s not cloned we will have to clone it. If it’s already cloned we simply pull the latest changes.
Some additional notes regarding this function:
- You will need to add your personal access token that you generate from Github in the .env file of your project (if you don’t have one defined, you will have to create it). If you don’t know how to create the token, it is explained here.
- This function takes into account the repository branch and you will have to indicate it in order for it to work correctly.
- I have set a specific repos folder inside my root folder where the schema will be cloned. This can be changed by modifying the function above.
And just like that, we are able to clone our repo from Git.
Building and Running the API
Now that we have the Graphql schema fetched, let’s load it into our API!
Firstly, we will need the GraphQL server node module called graphql-yoga (you can see it’s definition here) to create the server. We will also import all the GraphQL tools needed to load a schema from .graphql files. Finally we also need our marvelous function that we developed in our previous part to fetch the schema (this refers to the cloneAndPullRepo.js mentioned below):
In order to start our API we need some inputs. These are:
- The Git user whose repo we need to clone
- The Git repository we need to clone
- The Git repository branch we need to clone.
We are going to get these inputs as arguments when we run our API Server. Then, we are going to use them to pull (or clone) the latest version of the GraphQL schema we need to use.
Now it’s time to load the schema! We will use the graphql-tools module to load the schema using all the files in our repos folder that have a .graphql extention. We will also define the resolvers (for now empty but it’s up to you to build the functionality you want for your API).
Note that the constant called globPath is defined as “./**/*.graphql”. This tells our loader to create the schema using all the .graphql files it finds in all the sub-directories that the project has.
And with that we are almost done. Now it’s time to put it all together and run the server. Here is the complete definition of our NodeJS and Graphql Server:
To run the server we can execute the following npm and node commands:
Final thoughts
Having your Graphql API definition in Git (Github or Gitlab) is a very elegant and efficient way to manage the changes that it may experience.
The possibility of using different branches when you clone and pull your API allows you to, for example, test the final schema before updating it to the production environment. We can use a branch dev and make our changes there. Once pushed, we can reload our API in the development environment (make the development environment run the server with the dev branch version) and make all the tests we want. If all is successful we merge it with master and reload the server in production. There is no need to modify any code of our server or install a new version (just reload the current one).
Having the schema public in Git also let’s us maintain the “privacy” of our server project since we don’t need to upload the NodeJS project in Git. This way, external users can suggest and modify the schema but cannot view the internal server code.
These are some of the advantages an Git updated Graphql server offers. I’m sure that there are many more (as well as drawbacks for sure) that I have not seen but I encourage you to build the server and test all the possibilities it offers yourself.
Happy Coding! :)