Run Angular on GitHub Pages

Lesson Goal

By the end of this lesson, the student will be able to deploy an Angular project on GitHub Pages.

1. Level 0 Understanding

Angular is used to build web applications. But GitHub Pages does not run Angular source code directly. GitHub Pages can only host static files like HTML, CSS, and JavaScript.

2. Install Required Tools

Before starting, install Node.js, npm, Git, and Angular CLI.

Check Node, npm, and Git

Copynode -v
npm -v
git --version

Install Angular CLI

Copynpm install -g @angular/cli

Check Angular CLI

Copyng version

3. Create a New Angular App

We will create a sample app called:

Copyprogrammers-picnic-angular-demo

Create Project

Copyng new programmers-picnic-angular-demo

When Angular asks questions, choose simple options:

Go Inside Project

Copycd programmers-picnic-angular-demo

Run Locally

Copyng serve

Open this in the browser:

Copyhttp://localhost:4200

4. Edit the Angular Home Page

Open this file:

Copysrc/app/app.html

Replace the content with this:

Copy<main class="page">
  <section class="hero">
    <h1>Programmers Picnic Angular Demo</h1>
    <p>Built by Champak Roy</p>
    <p>This Angular project is running on GitHub Pages.</p>
  </section>
</main>

Now open:

Copysrc/app/app.css

Add this CSS:

Copy.page {
  min-height: 100vh;
  display: grid;
  place-items: center;
  background: #fff7ed;
  color: #241407;
  font-family: Arial, sans-serif;
}

.hero {
  max-width: 720px;
  padding: 48px;
  border-radius: 28px;
  background: white;
  box-shadow: 0 20px 50px rgba(120, 53, 15, 0.15);
  text-align: center;
  border: 1px solid #fed7aa;
}

.hero h1 {
  color: #d97706;
  font-size: 42px;
  margin-bottom: 12px;
}

.hero p {
  font-size: 20px;
}

5. Push the Angular Project to GitHub

Create a new GitHub repository with this name:

Copyprogrammers-picnic-angular-demo

Then run these commands inside your Angular project folder:

Copygit init
git add .
git commit -m "Initial Angular project"
git branch -M main
git remote add origin https://github.com/YOUR_GITHUB_USERNAME/programmers-picnic-angular-demo.git
git push -u origin main

6. Understand the Most Important Part: Base Href

A normal website may run from the root path:

Copy/

But a GitHub Pages project site usually runs from a repository folder:

Copy/programmers-picnic-angular-demo/

Correct build command:

Copyng build --configuration production --base-href /programmers-picnic-angular-demo/

7. Deploy Angular to GitHub Pages

The easiest beginner method is to use angular-cli-ghpages.

Add Deployment Package

Copyng add angular-cli-ghpages

Deploy

Copyng deploy --base-href=/programmers-picnic-angular-demo/

Now open your GitHub repository and go to:

CopySettings → Pages

Choose:

CopySource: Deploy from a branch
Branch: gh-pages
Folder: / root

Your final site will be:

Copyhttps://YOUR_GITHUB_USERNAME.github.io/programmers-picnic-angular-demo/

8. Add Useful npm Scripts

Open:

Copypackage.json

Inside the scripts section, add:

Copy"build:github": "ng build --configuration production --base-href /programmers-picnic-angular-demo/",
"deploy:github": "ng deploy --base-href=/programmers-picnic-angular-demo/"

Now you can deploy using:

Copynpm run deploy:github

9. Fix Angular Routing on GitHub Pages

If you use Angular routes like /about or /courses, the app may show 404 when the browser is refreshed.

Beginner-friendly fix: use hash routing.

Your URLs will look like this:

Copyhttps://username.github.io/repo/#/about

Open:

Copysrc/app/app.config.ts

Use this router setup:

Copyimport { ApplicationConfig } from '@angular/core';
import { provideRouter, withHashLocation } from '@angular/router';

import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes, withHashLocation())
  ]
};

10. Common Errors and Fixes

11. Final Deployment Checklist

12. Student Assignment

Create and deploy an Angular app called:

Copystudent-dashboard-angular

The app should contain:

Expected Final URL

Copyhttps://YOUR_GITHUB_USERNAME.github.io/student-dashboard-angular/

Final Command Summary

Copyng new programmers-picnic-angular-demo
cd programmers-picnic-angular-demo
ng serve

git init
git add .
git commit -m "Initial Angular project"
git branch -M main
git remote add origin https://github.com/YOUR_GITHUB_USERNAME/programmers-picnic-angular-demo.git
git push -u origin main

ng add angular-cli-ghpages
ng deploy --base-href=/programmers-picnic-angular-demo/

13. Change GitHub Pages URL to Custom Domain

Till now, our Angular app was planned for a GitHub Pages URL like this:

Copyhttps://YOUR_GITHUB_USERNAME.github.io/programmers-picnic-angular-demo/

Now we want to run the same Angular app on our own subdomain:

Copyhttps://angular.learnwithchampak.live/

Old GitHub Pages URL

Copyhttps://YOUR_GITHUB_USERNAME.github.io/programmers-picnic-angular-demo/

For this old URL, the deploy command was:

Copyng deploy --base-href=/programmers-picnic-angular-demo/

New Custom Domain URL

Copyhttps://angular.learnwithchampak.live/

For this new custom domain, use this deploy command:

Copyng deploy --base-href=/

Step 1: Create CNAME File in Angular Project

In your Angular project, create a file named:

Copypublic/CNAME

Inside this file, write only the custom domain:

Copyangular.learnwithchampak.live

Step 2: Save and Push the CNAME File

Copygit add .
git commit -m "Add custom domain"
git push

Step 3: Deploy Angular Again

Because the app will now open from the root of the custom domain, deploy with:

Copyng deploy --base-href=/

Step 4: Add the Custom Domain in GitHub

Open your GitHub repository and go to:

CopySettings → Pages → Custom domain

Enter this domain:

Copyangular.learnwithchampak.live

Then click Save.

Step 5: Add DNS Record

Go to the DNS manager for learnwithchampak.live. Add this record:

Example:

CopyType: CNAME
Name: angular
Value: programmer-s-picnic.github.io

Step 6: Wait and Test

DNS changes may take some time. After that, open:

Copyhttps://angular.learnwithchampak.live/

Step 7: Enable HTTPS

After GitHub verifies the DNS, go to:

CopySettings → Pages

Enable:

CopyEnforce HTTPS

Final Command Summary

Copy# Create CNAME file
echo angular.learnwithchampak.live > public/CNAME

# Save the change
git add .
git commit -m "Add custom domain"
git push

# Deploy for custom domain root
ng deploy --base-href=/

Common Mistakes