Client Side JavaScript Development with GitHub

There are a number of ways you can do simple client side JavaScript development with GitHub.

1. browser alone (not recommended)
2. GitHub Desktop (or other git client)
3. GitHub Destkop and Node.js for Jest and ESLint

Browser Alone (not recommended)

In theory, you can do client side JavaScript development in GitHub using only your web browser. You can edit files directly in the browser using the GitHub web application. If you configure your repository for GitHub Pages, then you can test your web site in the browser as well.

For GitHub Pages to work, the repository either has to be public or you have to have a paid GitHub subscription. If you are using a free GitHub account and the repository is not public, you can make it public as follows.

1. Go to the “Settings” tab for the repository and then choose the “General” sub-list from down the left-hand side if it is not already selected.
2. Scroll all the way to the bottom of the page to the “Danger Zone” section and click on the “Change Visibility” button and choose the “Change to public” option.
3. Confirm that you want to make the repository public and also that you understand the effects and make the repository public (there are a lot of clicks here!)

To configure the repository for GitHub Pages, follow these steps.

1. Go to the “Settings” tab for the repository and then choose the “Pages” sub-tab from list down the left-hand side.
2. In the “Build and deployment” section, choose “Deploy from a branch”.
3. In the “Branch” section, chose the appropraite branch (probably “main”).
4. Choose the folder to publish (either “/” or “/docs”).
5. Click on the “Save” button.
6. If you refresh this page, in a few mintutes it will give you a link that you can click on to see the published site.

You can practice with this template repository. Sign into GitHub if you have not done so already. Click on the “Use this template” button and choose “Create a new repository”. Then you can follow the steps above. When you are configuring the repository for GitHub Pages, be sure to choose the “/docs” folder.

The reason I say this method is not recommended is because of the rapid edit-test-debug cycle that is associated with client side JavaScript development (well, all software development). Usually, when you are developing software, you want to make a small change to the code and test it immediately. With this method, if you edit a file using the GitHub web editor, you will have to commit every change and wait for GitHub pages to regenerate the site so that you can test the change. This could possibly take several minutes for each change. For this reason, I recommend doing client side JavaScript locally on your own computer.

GitHub Desktop (or other git client)

You will be more productive if you do your client side JavaScript development locally on your own computer. In order to do this, you will need to install GitHub Desktop or other git client on your computer.

Use GitHub Desktop to clone the repository to your own computer. You can use any text editor to edit HTML, CSS, and JavaScript. I recommend that you install Visual Studio Code.

By developing locally, the edit-test-debug cycle is much faster. After making a change to a file, you just need to save it and re-load the page in your browser. To load local web pages in your web browser, use the “CTRL-O” key combination and browse to the file that you want to open. If the page is already loaded in your browser, I recommend doing a “hard” refresh to make sure the browser picks up the changed files. You do a hard refresh by holding down the “SHIFT” key on the keyboard and then clicking on the refresh page icon in your browser toolbar while keeping the “SHIFT” key depressed.

This way, you can rapidly debug your JavaScript without having to “commit” after every edit. Once you have complete feature debugged, then you can “commit” (and “push”) and then move on to working on the next feature in your application.

Try using GitHub Desktop and Visual Studio Code with the sample repository that you created above.

GitHub Destkop and Node.js for Jest and ESLint

The sample repository contains automated tests that are run using “Jest” to verify the expected JavaScript behaviour on every “commit” (and “push”). You can see the results of the automated tests as follows.

1. After a “commit” (and “push”) go the “Actions” tab for the repository in the GitHub web application. You will be taken to a page that lists the “workflow” runs for the repository.
2. Click on the title link for the topmost run which is the most recent. You will be taken to a page that shows more detail for the workflow run.
3. In the “Annotations” section of this page, click on the “build (18.x)” title link. You will be taken to a page that lists the outcome of the automated tests.
4. You can scroll through the output and try to figure out what the problems are.
5. Make the requried changes and “commit” (and “push”) the changes. After the “push” GitHub starts a new workflow to run the automated tests again. Go back the “Actions” tab to review the workflow status. When the workflow completes, you can review the results again as described above.

You may be satisfied with allowing GitHub to run the tests for you. There is obviously a bit of a delay waiting for the results. If you are willing to install additional software on your computer, you can run the automated tests locally which will speed up the edit-test-debug cycle even further.

You can use Node.js to run the automated tests locally on your computer. JavaScript normally runs inside a web browser. Node.js allows us to run JavaScript outside a web browser, either on a desktop or laptop or server computer.

To run the automated tests, you will need to install Node.js on your computer first. I recommend installing the current “LTS” release (18.x.x as of this writing).

For Windows, start the “Node.js Command Prompt” from your Windows Start menu (you will have to scroll way down to the “N” section and inside the “Node.js” folder). At the command prompt, install “yarn” as follows.

corepack enable
corepack prepare yarn@stable --activate

The above only has to be done once. Yarn will be available to all your projects now.

To run the automated tests locally, you will have chage the working directory of the command prompt to the root directory of your repository. This will be different for everyone depending on where you cloned the repository and the name of the repository, but might be something like this (first selecting the correct drive and then the correct path).

C:
cd \Users\johndoe\projects\dgl113week01demo

Once you have placed yourself in the correct directory, you can install the project dependecies.

yarn install

The dependencies only need to be installed once per repository.

Finally, you can run the automated tests.

yarn run test

Now you can make changes to your code and re-run the automated tests locally using the above command without having to commit and push the changes the repository and waiting for the GitHub action to complete.

The sample project is also configured for ESlint and Visual Studio Code. ESlint is software that does basic JavaScript syntax and style cheking on your code.

To use ESlint and Visual Studio Code follow these steps.

1. Open Visual Studio Code.
2. Click on the Extions manager icon.
3. Search for “ESLint”.
4. Install the extension.
5. Click on the “gear” icon to manage the extension.
6. Choose “Extension Settings”.
7. In the top right of the application click on the “Open Settings (JSON)” icon.
8. Paste the follwing into the window.

{
    "eslint.format.enable": true,
    "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
    },
    "eslint.packageManager": "yarn",
}

Save the file and close the settings tabs.

Now when you are editing a pure JavaScript file in the project, ESLint will highlight recommendations and when you save the file, it will try and fix the file as best it can.