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

1. Understanding the stack
2. Setting up the development environment
3. Understanding the project structure
4. 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.

I had written simple HTML, CSS and Javascript code before, but the whole Node.js infrastructure was foreign to me. One of the greatest challenges I faced was to understand how the pieces in the infrastructure were related to one another. As such, I’ll try my best to summarise what I’ve learnt.

What is Node.js?

The JavaScript language was traditionally used for writing scripts on the client side, ie. being executed in the user’s web browser. Node.js allows us to run JavaScript on the server side, without having to rely on other languages (like PHP).

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?

React is a front-end javascript library for building web applications.

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.

1. Install Git
2. Install Node.js
3. Install Yarn

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:

1. Play around with the app. For example, it will be more obvious that utils/modules-search.js carries 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.
2. 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.

Head to v3/src/js/views/AppContainer.jsx

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.

Head to /v3/js/views/static.

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.

Routing

Let’s set-up the routing so that /awesomepage brings us to our awesome new page.

Head to /v3/src/js/routes.jsx .

Import our page to this file,

Then route it to /awesomepage.

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