You can publish an Angular app to GitHub Pages by building it as a static site and pushing the compiled output to a special branch that GitHub Pages serves. The simplest and most reliable method today is using the angular-cli-ghpages tool, which automates the entire process. This approach is widely recommended and actively maintained Github. Other guides outline similar steps—build, adjust the base href, and deploy to the gh-pages branch—but the CLI tool removes most of the manual work DEV Community CoreUI.
It’s a nice way to demo a repository.
Here’s an angular app that I’m working to demo about building arpeggio patterns and chord progressions.
https://michaelprosario.github.io/music-playground/
How deployment works
GitHub Pages hosts static files from a branch in your repository. Angular apps are static once built (ng build), so the goal is to:
- Build the app with the correct base href so routing works.
- Publish the
dist/output to thegh-pagesbranch. - Enable GitHub Pages for that branch.
The angular-cli-ghpages package automates all three steps.
Step-by-step deployment using angular-cli-ghpages
1. Install the deployment tool
npm install -g angular-cli-ghpages
2. Build your Angular app for production
Replace your-repo-name with the actual GitHub repository name:
ng build --configuration production --base-href "/your-repo-name/"
This ensures Angular generates correct URLs for GitHub Pages, which serves your app from a subpath.
3. Deploy to GitHub Pages
From the root of your Angular project:
npx angular-cli-ghpages --dir=dist/your-project-name/browser
The tool will:
– Create or update the gh-pages branch
– Push your built files to it
– Configure the branch for static hosting automatically CoreUI
4. Enable GitHub Pages (if not already enabled)
In your GitHub repo:
- Go to Settings → Pages
- Set Source to the
gh-pagesbranch - Save
Your site will be available at:
https://<your-username>.github.io/<your-repo-name>/
Alternative manual approach (if you prefer not to use the tool)
Some guides walk through the manual method: build the app, copy the dist/ folder into a gh-pages branch, and push it yourself GeeksForGeeks Angular Minds. This works but is more error‑prone, especially around routing and base href.
Common pitfalls to avoid
- Incorrect base href: Without
--base-href "/repo-name/", your app will load locally but break on GitHub Pages. - 404 on refresh: GitHub Pages doesn’t support Angular’s client-side routing natively. The CLI tool automatically adds a
404.htmlfallback to fix this. - Wrong dist folder path: Make sure the
--dirpath matches the actual folder name insidedist/.
If you want, I can help you generate the exact commands for your specific repo name and Angular project structure.
Leave a Reply