From Localhost to Live: A Guide to Publishing Your React App on GitHub Pages

Uncategorized

You’ve built an awesome React app. It runs perfectly on localhost:3000, but now you want to share it with the world—to show a potential employer, get feedback from a friend, or simply have it live on the internet.

The great news is you don’t need to pay for a hosting service for your portfolio or test projects. GitHub Pages is a fantastic, free service that lets you host a static website directly from your GitHub repository. This guide will walk you through the entire process step-by-step.

Prerequisites

  • A React app created with Create React App.
  • A GitHub account.
  • Node.js, npm, and Git installed on your machine.

Step 1: Create a GitHub Repository

First, your project’s code needs to live on GitHub.

  1. Go to GitHub and create a new repository. Give it a name that matches your project (e.g., my-react-portfolio).
  2. Open your terminal, navigate to your local React project’s root directory, and link it to the GitHub repository you just created.
# Initialize git (if you haven't already)
git init

# Connect your local project to the remote repository
git remote add origin https://github.com/your-username/your-repository-name.git

# Add, commit, and push your initial code
git add .
git commit -m "Initial commit"
git push -u origin main

Step 2: Add gh-pages and Update package.json

This is the most important step, where we configure the project for deployment.

  1. Install the gh-pages package as a development dependency. This package does all the heavy lifting of pushing your app to GitHub Pages.
    npm install gh-pages –save-dev
  2. Open your package.json file and make two crucial additions.First, add a homepage property at the top level. This tells React where your app will be hosted. Replace <username> with your GitHub username and <repository-name> with your repository’s name.
    {
      “name”: “my-react-app”,
      “version”: “0.1.0”,
      “homepage”: “https://<username>.github.io/<repository-name>”,
      “private”: true,
      // … rest of the file
    }
    Second, add predeploy and deploy scripts to the scripts object.
    “scripts”: {
        “start”: “react-scripts start”,
        “build”: “react-scripts build”,
        “test”: “react-scripts test”,
        “eject”: “react-scripts eject”,
        “predeploy”: “npm run build”,
        “deploy”: “gh-pages -d build”
      },
  • “predeploy”: “npm run build”: This script automatically runs before the deploy script. It creates an optimized, production-ready build folder containing your app.
  • “deploy”: “gh-pages -d build”: This is the main command. It takes the code from your build folder and pushes it to a new branch on your GitHub repository named gh-pages. This is the branch that GitHub will use to host your site.

Step 3: Deploy the App

With the configuration complete, deploying is now a one-command job. Run the following in your terminal:

npm run deploy

You’ll see some output in the terminal as your app is built and then pushed to GitHub. Once it says “Published,” you’re ready for the final step.

Step 4: Configure Your Repository’s Settings

You’ve pushed the code for your site, but you still need to tell GitHub to serve it.

  1. Go to your repository on GitHub.
  2. Click on the Settings tab.
  3. In the side menu, click on Pages.
  4. Under the “Build and deployment” section, change the source Branch from None to gh-pages. The root folder / (root) should be correct.
  5. Click Save.

After saving, the page will refresh. At the top, you’ll see a message: “Your site is live at https://<username>.github.io/<repository-name>/”. It can take a few minutes for the deployment to complete, so if you see a 404 error, give it a moment and then refresh.

Congratulations! Your React application is now live on the internet for everyone to see.