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

Motivation

Setting up a new Angular repository in GitHub is not rocket science. The introduction of a CD pipeline is easy too. In this tutorial I will give you a quick and easy step-by-step guide.

Create Angular App

Install the following prerequisites: Git and Node.js.

Angular CLI

I will use Angular CLI to create the initial project setup. I need to install the CLI globally using Node. The CLI version I am using is 18.2.2.

npm install -g @angular/cli

I want to create a template with typescript. I googled that and this leads my to an old and much older link. The older link takes me to a dead page. The trick is, that Angular is generated with typescript by default! So I open a terminal in the root folder where all my git repositories are. The CLI will create a subfolder with the name of my application.

ng new sample-angular-typescript-githubpages

I have some options when I create the application. I choose CSS and no server-side rendering. The template includes a .gitignore and I can push it directly to GitHub.

I can run npm install without any vulnerabilities. But when I run npm ci I get warnings about three deprecated packages. The dependencies are caused by the karma test runner. So I override the version of glob and rimraf in my package.json below devDependencies.

"overrides": {
    "glob": "^9.0.0",
    "rimraf": "^4.0.0"
  }

But I rejoice too soon. Now the tests (ng test) are no longer running. So I roll back the changes and hope for the best. The issue is only one month old.

Run tests locally

When I run the test command a Chrome instance pops up. I have to select a default search engine every time I start the tests. As this is annoying, follow the advice of clever people. First, follow the advice of the second comment, generate a karma.conf.js and insert the snippet from the first comment.

Build and continuous deployment

I create a .github/workflows folder and a builddeploy.yaml with the following content in it. This time I select the right NodeJs version, as 22 is not LTS yet.

name: Deploy Angular 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: '20'
      - name: Install Dependencies
        run: npm ci
      - name: Build
        run: npm run build -- --configuration production --base-href /${{ github.event.repository.name }}/
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'dist/${{ github.event.repository.name }}/browser/.'
  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 produced artifact in the workflow run overview.

There is one improvement compared to the react tutorial. I pass two parameters to the npm run build. These parameters are then passed to ng build. The first parameter declares that I want the production configuration and the second is the base-href for my application. It must be the name of the GitHub repository framed by slashes. You can also use a full URL instead.

When I push the file, a workflow run starts automatically . It fails because the GitHub's default configuration 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 'deploy' job. The already built artifact 'github-pages' will be reused.

After the job re-run succeed, I finally see my GitHub Page. You can see the full code in my GitHub repository.

Conclusion

The setup of an Angular app is more straightforward than in my React tutorial. Angular, GitHub and the community have done a great job making life easy for developer's . 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.17.0
• NPM: 10.8.2
• Angular CLI: 18.2.2

Samples

I created a sample application on GitHub:

Here you can see the deployed version: