Update: This post is outdated with the introduction of NUSMods R.
The NUSMods team is super helpful and if you need any help with understanding the codebase, be sure to hit up the @nusmods Telegram group!
Ever since I started learning programming, I had been hearing a lot about open-source. I thought the idea of open-source was stupid. Why would anyone invest their time in something that doesn’t directly help them make more money or save more time?
However, my opinions changed greatly after I started working on NUSMods. I learnt so much in such a short span of time. Many of my friends who use NUSMods daily were also surprised to learn that I was a contributor to NUSMods. Today, I take pride in contributing to code for the community.
When I first started working on open-source, everything seemed so daunting. I hope that by documenting my progress, I’ll be able to help beginners who are on the same path as me.
What in the world is NUSMods?
NUSMods is an open-sourced web app that makes it really easy for students of NUS (National University of Singapore) to plan their time tables. It was developed by a few of my seniors at NUS to solve a problem they were facing — because it was really difficult and time consuming to plan time tables on paper.
Zhi An, who’s a frequent contributor to NUSMods, introduced me to the project at the start of 2017. He told me that the NUSMods core team were porting the old NUSMods page to a new v3 version. I was excited to find out what the code for NUSMods looked like, since I use NUSMods on a daily basis.
Table of contents
- Understanding the stack
- Setting up the development environment
- Understanding the project structure
- Can we finally start coding now?
Understanding the stack
Before starting work on an open-source project, it is important to familiarise yourself with the stack that the software is using. NUSMods uses React, which runs on Node.js.
What is Node.js?
Node.js is currently being used by many companies like Netflix, PayPal, and even Medium!
Check out this discussion if you’re interested in reading more about Node.js.
What is React.js?
It is open-sourced and being maintained by Facebook. What does this mean for us developers? Sometimes having great support for a framework means that it will be easier to find a solution when one runs into bugs, or be more sure that the time invested in learning the technology is going to be worth it since it is here to stay (at least for the next few years).
What is a package / npm / Yarn?
Often when developing software, developers want to create a feature, but hey, this feature has already been written by someone else before! So instead of creating these features from scratch, we download these snippets of code to use in our software to save time, and these code snippets are called packages.
npm makes it really easy to install and manage these packages. For example, installing react into a project is as easy as
> npm install react
Sometimes when projects get large, it may become difficult to install and manage all these packages, and setting up the development environment can get very painful.
Yarn is a relatively new package manager developed at Facebook that aims to solve some quirks that npm has.
What is Git / GitHub?
As a beginner, Git took me a really long time to understand.
In essence, Git is a version control system for software. You can think of Git as ‘save points’ for code. When writing code, it is important to make commits (save points) so that we can get back to them later when we make a mistake down the road later. There are many more uses to Git, which you can learn about here.
GitHub is a tool that allows one to host their repositories in the cloud, and lets developers to collaborate with one another on a piece of software. I’ll be talking more about GitHub in the next part of this series.
Setting up the development environment
Setting up the development environment was the hardest part for me at first because it was impossible to know what the commands did without a decent understanding of the software stack.
Following the instructions on the v3 github repositary page, I installed the various software required.
Next, I had to clone the NUSMods repository onto my desktop via the command line.
Note that the Windows Command Prompt is very different from Linux / Apple Bash shells. I use Windows, but you can try referring to this short command line guide for other systems if you are unsure of how to use the command line.
The Command Line and Git are very powerful tools so be sure to take some time to learn them well!
> git clone https://github.com/nusmodifications/nusmods.git
This clones a copy of the NUSMods files to my desktop
Remember the Yarn tool that we talked about just now? We’re going to use it to retrieve the dependencies (packages) for NUSMods.
> yarn> yarn run build:dll # Do this whenever you update dependencies or change vendor bundle> yarn start
Cool, navigating to http://localhost:8080/ in the browser, we can now find a copy of NUSMods running on the local server.
Understanding the project structure
Try playing around with the app for a while to get a feel of how the app comes together.
When you’re ready, head to
/nusmods/v3/src. We’ll focus on this part of the source code first to understand how the code is structured..
It may be very daunting for someone new to the code to understand where all the various files are. For me, I do these to help myself understand the code better:
- Play around with the app. For example, it will be more obvious that
utils/modules-search.jscarries the code for the module search bar after becoming more familiar with the app. In fact, this is pretty easy for me since I use NUSMods on a daily basis.
- Learn the stack well. NUSMods uses the React-Redux-Webpack stack, which has certain conventions in place that programmers try to follow, in order to make their code easier to understand. There are several good guides online that will take a significant amount of time to go through, but I promise that it will be worthwhile.
Can we finally start coding now?
The NUSMods core team has kindly written up a guide to ‘getting your feet wet’. One of the first tasks are to create a button on the v3 navigation. Let’s go ahead and try that.
Creating a new button
First we need to find the file which holds the code for the navigation bar.
There we see the code the code that holds our navigation bar. Note that some understanding of HTML is required for this part. Take some time to get familiar with how React jsx code is structured as well.
Simply paste a copy of the buttons above, save the file and see the changes on your browser immediately.
Notice how clicking on the button routes me to the
/settings page, because I haven’t changed the routes.
Setting up a new page
We want to make our awesome new button take us to an awesome new page. Let’s go ahead and create our awesome new page.
This folder contains all the static pages.
Create a new page by copying any of the other static pages and renaming it.
Make sure to rename the component name and page contents as well.
Let’s set-up the routing so that
/awesomepage brings us to our awesome new page.
Import our page to this file,
Then route it to
Hit save and navigate to
/awesomepage to see our new page!
Finally, let’s link our new button to the new page.
Now test our button and viola, it should work perfectly.
I hope that this guide has made it a little easier for you to get into open-source / NUSMods.
I will be writing more parts to the series where I’ll talk about GitHub and creating pull requests, the Redux paradigm and software testing, be sure to follow me to receive updates when the new parts are up!
Helpful Resources and Links
Using the command line
Git and version control
Really simple git reference (Really short read that’s easy to digest)
When to use node.js?
Beginner’s guide to npm
What is Yarn
Intro to React
React + Webpack + Redux video series