Chess Web Programming: Part Three: Deploying your Application

In October 2023, I began learning modern web programming and used Chessboard Magic as my first major project. What started as a way to practice my skills has grown into something much larger—Chessboard Magic now includes 34 different chess-based applications! Building it was both a rewarding challenge and a fantastic way to dive deeper into web development, and now I’m excited to share this journey with you.
Throughout this series, I've shared insights and practical steps for building chess applications. In Part One, we covered the fundamentals: setting up a functional chessboard with react-chessboard and using chess.js for move validation. This laid the foundation for the interactive experience that makes Chessboard Magic engaging. Then in Part Two, we took things further by integrating Stockfish, a powerful open-source chess engine, to provide the best move in any position. This feature adds a robust layer of analysis and brings the game to life with real-time insights.
Now, in Part Three, it's time to share our work with the world. In this article, I’ll guide you through the deployment process, focusing on free options for getting your application live, like GitHub Pages. By the end of this guide, you’ll be ready to publish your application, making it accessible to others who want to explore, analyze, and enjoy chess through your project.
Let’s dive into making your application live!

Note: If you are new to programming, I would highly recommend taking a little time to look into Git. It’s a fundamental tool for version control, collaboration, and managing code, and is essential for deploying projects like this one.

Sign Up for GitHub

What is GitHub?
GitHub is a platform designed for storing and managing code, built on top of Git—a popular version control system. It allows you to track every change you make to your code, so you can go back to previous versions if something breaks or if you want to revisit an earlier version of your project. Think of GitHub as both a safe place to store your code online and a powerful tool for collaborating with others on projects.
Here’s why GitHub is widely used and especially helpful for web developers:

• Version Control: GitHub records every change you make to your code, making it easy to track, manage, and even revert changes. This feature is invaluable when working on complex projects, as it allows you to try new things without the fear of losing past work.
• Collaboration: GitHub makes it easy to work with others by allowing multiple people to contribute to a single project. Each person’s contributions are saved separately, and GitHub offers tools to combine and manage everyone’s changes.
• Free Hosting with GitHub Pages: GitHub offers a service called GitHub Pages, which lets you publish your code as a live website. This means that, with a few steps, you can deploy and share your web application with anyone online—for free.

In this guide, we’ll use GitHub as a central place to store your project and then deploy it live using GitHub Pages. Here’s how to get started:

1. Go to GitHub: Open GitHub in your browser.
2. Click "Sign up": Follow the prompts to create an account. You’ll need to enter a username, email, and password.
3. Verify Your Email: GitHub will send a verification email. Click the link in the email to activate your account.

Once your account is set up, you’ll have access to all of GitHub’s free tools, including GitHub Pages! In the next steps, we’ll guide you through creating a GitHub repository (project folder) and uploading your project to GitHub.

Install Git

What is Git?
Git is a tool that helps you keep track of changes to your project. Imagine you’re working on a project and want to save each step as you go so you can go back if needed. Git lets you do this by creating "snapshots" (called commits) of your project. Each commit saves the current state of your project, so you can rewind to any previous point if you need to.
Here’s why Git is helpful:

• Save Points: Git lets you save different versions of your project. If something goes wrong, you can easily go back to an earlier version.
• Experimenting Safely: You can try new ideas without risking your main project. Git lets you create “branches,” or test versions of your project, that you can later combine back into your main work if you like the changes.
• Collaborating with Others: If you’re working with a team, Git helps everyone stay organized by tracking who made which changes. This way, everyone’s work can be combined smoothly.

Why Do You Need Git with Visual Studio Code?
Visual Studio Code (VS Code) is designed to work well with Git, so you can save, track, and manage changes without ever leaving the editor. However, VS Code doesn’t come with Git installed. To use Git’s features in VS Code, you’ll need to download and install Git first.

How to Install Git

1. Download Git: Go to Git Downloads and choose the right version for your computer.
2. Install Git: Open the downloaded file and follow the steps to install Git.
3. Check That Git Installed Correctly: Once Git is installed, open a terminal or Command Prompt on your computer. Type:

git --version

1. If you see a version number, Git is ready to use!

After you install Git, you’ll be able to use VS Code’s built-in Source Control panel to save, track, and upload your project changes with ease.

Create a New GitHub Repository

Now that you have Git installed, it’s time to create a repository (often shortened to “repo”) on GitHub. Think of a repository as a special folder on GitHub that will hold your project files, allowing you to save, share, and manage your project online.

What is a GitHub Repository?

A GitHub repository is like a project folder that you store on GitHub. It contains your project files and tracks changes over time, so you can revisit past versions if needed. Repositories make it easy to share your work, collaborate with others, and keep everything organized in one place.

How to Create Your Repository

1. Go to GitHub:
   • Open GitHub in your web browser and log in if you haven’t already.
2. Create a New Repository:
   • At the top-right corner of the GitHub homepage, click on the + icon and select New repository.
3. Set Up Your Repository:
   • Repository Name: Enter a name for your repository, such as myfirstchessapp. This name will also be part of your project’s URL on GitHub.
   • Description (Optional): You can add a short description to explain what your project is about (e.g., “My first chess app with web programming”).
   • Public vs. Private: Select Public if you want anyone to see your project. GitHub Pages requires a public repository to publish your site for free.
   • README (Optional): You can check the box to add a README file. A README file is like an introduction to your project and can include instructions or notes for users. We’ll add one later, so it’s okay to skip this for now.
4. Create the Repository:
   • Once you’ve filled out these details, click Create repository. GitHub will create a new, empty repository with the name you specified.
5. Get Your Repository’s URL:
   • After creating your repository, GitHub will display a URL that looks like https://github.com/your-username/myfirstchessapp.git. Copy this URL—you’ll use it in the next step to link your project folder on your computer with this new GitHub repository.

With your repository created, you’re ready to move to the next step, where we’ll link your local project to GitHub and upload your files.

Initialize Git, Commit Your Code, and Publish the Branch

This step will help you set up Git in your project folder, make an initial commit, and push your code to GitHub. After this, you’ll be able to manage everything directly from Visual Studio Code.

1. Open Your Project in VS Code and Open the Terminal

1. Open Visual Studio Code: Open VS Code and go to File > Open Folder. Select the folder where your project is stored (e.g., myfirstchessapp).
2. Open the Terminal: In VS Code, open the Terminal by going to View > Terminal or pressing Ctrl +(backtick). This will open a terminal at the root of your project, where you can enter Git commands.

2. Initialize Git in Your Project

Initializing Git in your project folder is the first step to making Git aware of your files so it can track them. This process sets up Git to work in your project folder, creating a hidden .git folder where Git will store all the information it needs to track your changes.
Let’s go through this step-by-step:

1. Open Your Project in Visual Studio Code:
   • Go to File > Open Folder and select your project folder (e.g., myfirstchessapp).
2. Open the Terminal:
   • In VS Code, go to View > Terminal to open a terminal at the bottom of the screen.
3. Initialize Git:
   • In the terminal, type: git init

After this, Git is ready to track your files, and you can move on to the next step.

3. Stage and Commit Your Files

Now that Git is set up in your project, we need to stage your files (prepare them to be saved) and then commit them (create a save point).

1. Stage All Files:
   • In the terminal, type: git add .
   • Press Enter. This command stages all files in your project, preparing them for the commit.
2. Create Your First Commit:
   • Now type: git commit -m "Initial commit"
   • Press Enter. This command saves the staged files with the message "Initial commit".

Your files are now committed, meaning Git has created a save point for this version of your project. You’re ready to link your project to GitHub in the next step.

4. Link Your Project to GitHub

To upload your project to GitHub, you need to connect your local project to the GitHub repository you created.

1. Copy the Repository URL:
   • Go to your GitHub repository page (e.g., https://github.com/your-username/myfirstchessapp).
   • Click the green Code button, then copy the URL (it should look like https://github.com/your-username/myfirstchessapp.git).
2. Add the Remote Repository:
   • In the VS Code terminal, type: git remote add origin https://github.com/your-username/myfirstchessapp.git
   • Replace your-username with your GitHub username.
   • Press Enter. This command links your local project to the GitHub repository.

Now your local project is connected to GitHub, and you’re ready to publish it. In the next step, we’ll push your code to GitHub to make it accessible online.

5. Publish Your Code to GitHub

Now that your project is connected to GitHub, let’s push your code online so it’s saved in your GitHub repository.

1. Go to the Source Control Panel:
   • In Visual Studio Code, click on the Source Control icon in the sidebar (it looks like a branch).
2. Click on Publish Branch:
   • In the Source Control panel, you should see a Publish Branch button at the top. Click it.
3. Confirm the Branch Name:
   • Visual Studio Code will publish your current branch, usually named main. If it asks for confirmation, make sure main is selected and confirm.
4. Sign In to GitHub (if prompted):
   • If you haven’t connected VS Code to GitHub before, it may ask you to sign in. Follow the prompts to log in.

Once the publish process is complete, Visual Studio Code will upload your project files to GitHub, and you’ll see a confirmation message.

Deploy Your Project Using npm and GitHub Pages

To automate the deployment of your project, we’ll use the gh-pages package. This package allows you to publish your project to GitHub Pages directly from the command line, making it quick and easy.

1. Install the gh-pages Package

In the terminal, run this command to install gh-pages as a development dependency:

npm install gh-pages --save-dev

Explanation: This command installs gh-pages, which will handle the process of uploading your project to a special branch on GitHub called gh-pages. GitHub Pages uses this branch to host your site.

2. Add a homepage Field in package.json

The homepage field in package.json tells GitHub Pages where your site will be hosted. Adding this field helps ensure that links and assets work correctly on your live site.

1. Open package.json:

   • In Visual Studio Code, go to the file explorer on the left side and find the file called package.json in the root of your project. Click to open it.

2. Add the homepage Field:

   • At the top of the file, add a new line directly after the opening { bracket. Type the following, replacing your-username with your GitHub username and myfirstchessapp with the name of your repository:

     "homepage": "https://your-username.github.io/myfirstchessapp",
     

   • Ensure you include the comma , at the end, as shown above, so that the rest of the file continues to work correctly.

   Here’s an example of what the beginning of package.json should look like with the new homepage field added:

   {
     "homepage": "https://your-username.github.io/myfirstchessapp",
     "name": "myfirstchessapp",
     "version": "0.1.0",
     "private": true,
     ...
   }
   

   • You’ll see other fields like name and version—just add homepage as the first entry.

3. Save the File:

   • Press Ctrl + S (or Cmd + S on Mac) to save your changes.

3. Add Deployment Scripts in package.json

Now we’ll add two scripts in package.json to handle the build and deployment steps.

1. In package.json, find the "scripts" section, which should look something like this:

   "scripts": {
     "start": "react-scripts start",
     "build": "react-scripts build",
     "test": "react-scripts test",
     "eject": "react-scripts eject"
   }
   

   Add the predeploy and deploy scripts inside the "scripts" section, so it looks like this:

   "scripts": {
     "start": "react-scripts start",
     "build": "react-scripts build",
     "predeploy": "npm run build",
     "deploy": "gh-pages -d build"
   }
   

   Explanation:

   • "predeploy": "npm run build" tells npm to run the build script first, creating an optimized production version of your app in the build folder.
   • "deploy": "gh-pages -d build" uses gh-pages to publish the contents of the build folder to GitHub Pages.

4. Build Your Project

Before deploying, it’s a good idea to manually build your project to make sure everything compiles correctly.
In the terminal, run:

npm run build

This command creates a build folder with all the production-ready files for your project. These files will be published to GitHub Pages.

5. Deploy Your Project

Now that your project is built, it’s time to deploy it to GitHub Pages! Run the following command:

npm run deploy

This command first runs the predeploy script to build your project, then runs deploy to publish the build folder to a branch called gh-pages on GitHub. GitHub Pages will use this branch to host your live site.

6. Access Your Live Site

After deployment, your site should be live at:

https://your-username.github.io/myfirstchessapp

Replace your-username and myfirstchessapp with your actual GitHub username and repository name.

Note: It may take a few minutes for GitHub to process the deployment. If your site doesn’t appear immediately, wait a moment and refresh the page.

Updating the Reference to Stockfish in App.js

When deploying to GitHub Pages, it’s important to adjust the file paths in your code to account for the way GitHub Pages serves your project. By default, GitHub Pages hosts your project under a subdirectory based on your repository name (e.g., https://your-username.github.io/repo-name). This affects any file paths that start with a /, as these will try to load from the root directory instead of your project’s subdirectory.

Why Update the Stockfish Path?

In App.js, if you load Stockfish with a path like /js/stockfish-16.1-lite-single.js, it works locally because it points to the root folder of your development environment. However, on GitHub Pages, this same path would point to https://your-username.github.io/js/stockfish-16.1-lite-single.js instead of the correct subdirectory, causing the file not to load.
To make sure Stockfish loads correctly on GitHub Pages, we’ll use process.env.PUBLIC_URL to dynamically generate the correct path, so it works both locally and in production.

Update the Stockfish Path in App.js

1. Locate the Stockfish Initialization in App.js:

   • Find the line in App.js where you load the Stockfish file, which should look something like this:

     const stockfishWorker = new Worker("/js/stockfish-16.1-lite-single.js");
     

2. Update the Path Using process.env.PUBLIC_URL:

   • Replace this line with the following:

     const stockfishWorker = new Worker(`${process.env.PUBLIC_URL}/js/stockfish-16.1-lite-single.js`);
     

     Explanation: process.env.PUBLIC_URL dynamically adjusts to the correct base URL. Locally, it defaults to /, but on GitHub Pages, it adjusts to your repository’s subdirectory (e.g., https://your-username.github.io/repo-name). This ensures that the Stockfish file loads correctly in both environments.

Redeploy Your Project

After updating the Stockfish path, redeploy your project to GitHub Pages to apply the changes:

1. Build the Project: npm run build
2. Deploy to GitHub Pages: npm run deploy
3. Verify the Deployment:
   • Once the deployment is complete, visit your GitHub Pages URL to confirm that the Stockfish file loads correctly.

By updating the Stockfish path to use process.env.PUBLIC_URL, you ensure that GitHub Pages serves the file from the correct location, avoiding broken paths and loading issues. This simple adjustment will make sure your app works seamlessly in both local development and production on GitHub Pages.

Note: Use process.env.PUBLIC_URL for all resource files (e.g., images, JavaScript files like Stockfish, CSS files) to ensure they load correctly on GitHub Pages. This approach adjusts paths automatically based on whether your app is running locally or on GitHub Pages, avoiding broken paths and missing resources.

Summary

In this blog, we explored the process of deploying a chess web application to GitHub Pages, with a focus on optimizing paths and resources for smooth loading in a production environment. Starting with the basics of initializing Git, creating a repository, and setting up deployment scripts, we then dived into the specific challenges of working with GitHub Pages, particularly how to correctly reference resource files like images and external libraries such as Stockfish. By using process.env.PUBLIC_URL for all resource paths, we ensured compatibility across both local and GitHub Pages environments, preventing common loading issues. Now, your chess app is live and fully functional on GitHub Pages, ready for users to enjoy!
If you have any questions or comments, post below and I will try to get back to you.

Learn More

• React – A JavaScript library for building user interfaces.
• react-chessboard – A React component for rendering a chessboard.
• chess.js – A library for handling chess game rules and move validation.
• Stockfish – A powerful open-source chess engine.
• stockfish.js – A JavaScript and WebAssembly version of Stockfish for web applications.
• GitHub – A platform for version control and collaboration.