Deploying Front-End freeCodeCamp projects on GitHub Pages for free

Introduction

As a mostly self-taught software developer, I love freeCodeCamp. It teaches you all the basics you need to get started with software development. The courses give you full freedom on how to deploy the final projects. However, this freedom may lead one down the path of sacrificing speed or comfort while coding. Naturally, you may end up asking yourself the question: What is the best way to deploy a freeCodeCamp project?

🐈‍⬛ Enter GitHub!

The main purpose of building these projects is to show that you do indeed have the skills that the course teaches you. Therefore, it makes perfect sense to put them in a public Git repository (e.g. on GitHub) and show that you have even more skills on top of that, such as writing clean code and commits. But GitHub also allows you to have your front-end project hosted publicly, completely for free, using GitHub Pages.

This is my way.

In this blog post, I will show you how I deploy my freeCodeCamp projects on GitHub Pages after finding out this way works the best for me.

⚠️ Note: Deploying this way is my personal preference, and therefore should in no way be viewed as the "correct" or "optimal" way.

Let me take you through my process of deployment.

The Roadmap

🛣️ Let's divide the process into its most important steps:

Setting up the project
Creating the GitHub repository and connecting to it
Setting up GitHub Pages
Adding the freeCodeCamp test suite CDN
Making the test suite appear on the /fcc route only (optional)

I'll be following these steps on a real freeCodeCamp project I need to build and deploy, particularly the Build a JavaScript Calculator project.

Project setup

There are multiple ways to set up a React project. I will be using Vite, as from my experience it is the fastest and most straightforward.

I'll create the project folder and name it web-calculator in this case. Then I'll open it in the terminal and set up the Vite project. I am using typescript, so I'll use react-ts as a template instead of react :

npm create vite@latest . -- --template react-ts
npm install

Creating the GitHub Repository

I'll start by creating a new repository on GitHub, which will serve as a home for the project. I'll make sure it is set to public and I won't initialize it with any of the things that GitHub offers me (I'll explain why later 🤫).

Creating a new repository

Here, I call the project web-calculator, the same as the project folder on my computer. This means it will be located at github.com/sevcak/web-calculator, sevcak being my GitHub username.

Now, I need to hook this up to the repo located on my computer, which has yet to be initialized.

Initializing and connecting to the repository

In the web-calculator folder, I'll initialize the Git repository and add the first commit:

git init
git add .
git commit -am 'intial commit'

(Note that I need to have Git installed to do this.)

Adding a remote

To connect to my remote repository, I hop to the remote's homepage, github.com/sevcak/web-calculator.

A quick setup window shows up because the repo is empty. This is because I initialized it without any of the options that GitHub offered me when creating the repo.

Empty GitHub repo homepage

To connect to the remote, I just copy and paste the code that I see at the …or push an existing repository from the command line code block into the terminal:

git remote add origin https://github.com/sevcak/web-calculator.git
git branch -M main
git push -u origin main

Now, the project is up on GitHub:

Setting up GitHub Pages

For the project to deploy with GitHub Pages, I need to do a little more work than I would have to if this was just an HTML project.

Creating a workflow

I'll create a GitHub Actions workflow for my project to handle the deployment. The workflow will be a YAML file located at .github/workflows/deploy.yaml.

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repo
        uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: 16

      - name: Install dependencies
        uses: bahmutov/npm-install@v1

      - name: Build project
        run: npm run build

      - name: Upload production-ready build files
        uses: actions/upload-artifact@v2
        with:
          name: production-files
          path: ./dist

  deploy:
    name: Deploy
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'

    steps:
      - name: Download artifact
        uses: actions/download-artifact@v2
        with:
          name: production-files
          path: ./dist

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Then, I have to grant read and write permissions to the workflow. I can do this on the GitHub project settings, in Settings > Actions > General > Workflow permissions:

Vite config

I have to add some more code to the Vite config file vite.config.js, which tells the project to use /web-calculator/ as the base on deployed builds:

// vite.config.js

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vitejs.dev/config/

export default defineConfig(({ command }) => {
  const config = {
    plugins: [react()],
    base: '/',
  }

  if (command !== 'serve') {
    config.base = '/web-calculator/'
  }

  return config;
});

This is necessary because GitHub Pages deploys the projects at [USERNAME].github.io/[REPO NAME]. In this case, the base of the deployed project will be sevcak.github.io/web-calculator/.

Now, I just need to push this to the remote:

git add .
git commit -am 'setup: add GitHub Actions deployment config'
git push origin main

After a bit of waiting for GitHub to deploy, I should see my project live at https://sevcak.github.io/web-calculator/:

Adding the freeCodeCamp test suite CDN

When submitting your certification project on freeCodeCamp, you should include their test suite, so anybody looking at your project can quickly and easily verify that it passes all tests.

Adding the test suite can be as straightforward as including a CDN in the <head> of the index.html file, like this:

<!-- index.html -->
<!-- ... -->
<head>
    <!-- ... -->
    <script src="https://cdn.freecodecamp.org/testable-projects-fcc/v1/bundle.js"></script>
</head>
<!-- ... -->

However, this would make the test suite appear even when it's not necessary. I prefer having another route that adds the suite on top of the homepage. This is where React Router comes in.

Setting up React Router

I'm using GitHub Pages, so this means I'm dealing with a strictly front-end application. Because of this, I will use React Router's HashRouter.

I'll install the react-router-dom package:

npm install react-router-dom

Then, I'll add the HashRouter to the app, precisely inside the main.tsx file. I'll also add a route where I will put the test suite later, let's say at /fcc :

// main.tsx

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import { HashRouter as Router, Route, Routes } from 'react-router-dom';
import './index.css'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Router>
      <Routes>
        {/* The route for the test suite */}
        <Route path="/fcc" Component={App}/>
        {/* The base route */}
        <Route path="/" Component={App}/>
      </Routes>
    </Router>
  </React.StrictMode>,
)

Now I can push the changes, so I can verify that my router works when deployed to GitHub Pages:

git add .
git commit -am 'setup: add React Router, set up HashRouter and `/fcc` route'
git push origin main

Now my test suite route should display at sevcak.github.io/web-calculator/#/fcc.

Adding the test suite to a specific route

If I inject the CDN inside the index.html file, the test suite will appear on all routes. To circumvent this, I'll download the test suite CDN and put it inside a file I'll name testSuite.js. I'll put the whole test suite code in an if statement that ensures the suite gets injected only on the /fcc route:

// testSuite.js
// This file contains a test suite made by freeCodeCamp
// The original suite is available at: https://cdn.freecodecamp.org/testable-projects-fcc/v1/bundle.js
if (window.location.hash === '#/fcc') {
    // The test suite code goes here
}

Now, I'll import the testSuite.js file in my index.html instead of the CDN:

<!-- index.html -->
<html lang="en">
  <head>
    <!-- ... -->
  </head>
  <body>
    <!-- ... -->
    <script src="/testSuite.js"></script>
  </body>
</html>

I'll push the changes to test if everything is working on the GitHub Pages end:

git add ..
git commit -am 'setup: add the freeCodeCamp test suite to the `/fcc` route'
git push origin main

After deployment, the test suite should appear at sevcak.github.io/web-calculator/#/fcc only:

Conclusion

🎊 My project is now deployed and set up! Now all that remains is to work on it, push the changes and on completion submit the sevcak.github.io/web-calculator/#/fcc route to freeCodeCamp.

🙏 For anyone reading this post, I am beyond grateful. I hope my process can be of even the smallest use to anyone who stumbles upon this blog post. Happy coding!