How to set up a typescript-based React application and deploy it directly to GitHub Pages using a CD GitHub action. A practical guide for 2024.

Motivation

I was new to React, Typescript, and GitHub Pages when I started this. I fell into some traps, mainly due to outdated suggestions, while creating my proof of concept. To avoid this for you, I will give you a quick and easy walkthrough.

Create React app

Install the following prerequisites: Git and Node.js.

Create the React app
I will use create-react-app to create the initial project setup. I start a terminal in the root folder where all my git repositories are located. A subfolder with the name of your application will be created.

npx create-react-app sample-react-typescript-githubpages --template typescript

The cra-template-typescript package does not need to be installed globally. I have uninstalled it for this tutorial. There is also no more switch typescript anymore for create-react-app.

The folder now contains a .git folder. I am removing it to push directly from Visual Studio Code to GitHub. I also renamed my ‘master’ to ‘main’ branch which has implications for the GitHub workflow I will introduce later.

Vulnerability warnings from npm

I get a notice that vulnerabilities have been found.

8 vulnerabilities (2 moderate, 6 high)

Npm suggests that I should run ‘npm audit fix’ to fix this. But this only introduces more vulnerabilities. Instead, I move the ‘react-scripts’ dependency in the package.json to ‘devDependencies’. After this step, I can run npm audit without the dependencies that are only used to develop the page.

npm audit --omit=dev

Build and continuous deployment

I create a .github/workflows folder and a builddeploy.yaml with the following content in it.

name: Deploy React to GitHub Pages

on:
  push:
    branches:
      - main # name of the branch you are pushing to

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install Dependencies
        run: npm ci
      - name: Build
        run: npm run build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'build/.'
  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: 'https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/'
    steps:
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Deploy
        uses: actions/deploy-pages@v4

This workflow uses the GitHub action actions/deploy-pages to deploy the artifact from actions/upload-pages-artifact to GitHub pages. I can also view and download the generated artifact in the workflow run.

When I push the file, a workflow run automatically starts. It fails because the default configuration of GitHub is currently to deploy GitHub pages from a specific branch. So I need to change the configuration of my GitHub repository.

I need to change the selection of the drop down box to ‘GitHub Actions’. As you can see ‘Deploy from a branch’ is declared as ‘classic’, which is usually a nicer word for ‘legacy’.

Now I need to re-run the failed jobs of my GitHub Action workflow. GitHub will only execute the job ‘deploy’ again. The already built artifact ‘github-pages’ will be reused.

The pipeline is now green and I see a link in my execution that I can click to go to my deployed GitHub page. The page is there because I am not getting a 404 error. But the page shows nothing.

Activating npm publish

The reason for this is a configuration in the package.json in my React app that prevents the page from being published. I have to change it to see my page. I also have to add the link to my GitHub Page, even though GitHub Copilot says I do not have to and the problem is somewhere else.

{
...
"private": false,
"homepage": "https://kinneko-de.github.io/sample-react-typescript-githubpages/",
...
}

After pushing and deploying I finally see my GitHub Page. You can see the full code in my GitHub repository.

Conclusion

Even with the traps, it took me only two hours to finally deploy my first React app. React, GitHub and the community have done a great job making the developer's life easy. Thank you for that ❤

Versions used

I will try to update this guide to the latest version to keep up with breaking changes in the tools. If you find something that does not work for you, please leave a comment. For a better overview, I list all versions used while writing this article.

• Node.js 20.12.2
• NPM: 9.8.1
• cra-template-typescript: 1.2.0
• create-react-app: 5.0.1

Samples

I created a sample application on GitHub:

Here you can see the deployed version: