There are two key web application development methods: multiple-page and single-page. The multiple-page approach usually works with a tightly coupled backend technology, like PHP or .NET MVC.
A typical single-page web application has a loosely coupled backend. In other words, single-page web applications have split client-side and server-side code.
Nowadays, the single-page development approach is popular because it brings higher maintainability factors, an impressive user experience, and good caching support. Frontend frameworks like Angular, React, Svelte, and Vue.js can be used for single-page web application development.
However, we need to have a static file server to publish the client-side code of a particular single-page application on the internet. You can either make your own static file server on a cloud service or use a static file-hosting service like GitHub Pages, which is a free service with a lot of benefits.
In this tutorial, I will show you how you can deploy your Angular application into GitHub Pages.
The Replay is a weekly newsletter for dev and engineering leaders.
Delivered once a week, it's your curated guide to the most important conversations around frontend dev, emerging AI tools, and the state of modern software.
GitHub Pages is a free service that allows developers to deploy their code repositories as static websites. In other words, you can expose your HTML, JavaScript, and CSS-like web content as a website via a GitHub repository when you use GitHub Pages, and you can also access all of GitHub’s other benefits and services. For example, you can integrate the GitHub Actions service to run some Angular unit tests for your single-page application.
Moreover, GitHub Pages offers you a free github.io subdomain. If you have a domain name already, you can easily use that as well.
If you already have an Angular application you’d like to use in this tutorial, you can skip to the next section.
Angular offers a CLI that we can use to create and manage Angular applications. Angular CLI also generates initial codes automatically for the given schematics. Enter the following command to install the CLI.
$ npm install -g @angular/cli
Then, enter the following command to scaffold a new application.
$ ng new yourappname
Once the initial files have been created, you can start the local development server to see your newly created application.
$ cd yourappname $ ng serve --open
After that, implement your web application by creating components as you wish. You can test the application logic without even fully reloading your application because Angular supports hot module reload.
To get started, you’ll need to create a GitHub repository for your static website. If you haven’t stored your code in GitHub yet, create a new repository. If you need to have your website working at the root of your github.io subdomain, name your repository as <username>.github.io. Otherwise, your website will be published to <username>.github.io/<repositoryname>. You can also use a custom domain as a name for your GitHub repository.
By default, Angular CLI initializes a Git repository for you. Therefore, you need to add a new remote reference pointing to your new GitHub repository to push your code and static files.
Enter the following code to set a new remote reference.
$ git remote add origin https://github.com/<username>/<repositoryname>.git
Since Angular CLI alone doesn’t support the GitHub Pages deployments, you’ll need to add the Angular GitHub Pages external library by entering the following command:
$ ng add angular-cli-ghpages
The above command will extend the CLI by adding the GitHub Pages deployment support.
Now the CLI is ready to deploy your application into GitHub Pages. You can use the deploy command to deploy your current Angular application, as shown below.
$ ng deploy --base-href=/<repositoryname>/
The above command will build your application and push the final static files to the gh-pages branch. After the first successful deployment, GitHub will automatically enable the GitHub Pages feature for the new repository. More information is available in the Settings tab, under the GitHub Pages section, as shown below.
Your website should be accessible via https://<username>.github.io/<repositoryname> . You can see that the example application I created is live:
The --base-href option in the deploy command will set the HTML <base> tag with the href property. If you are publishing your application to the root of your github.io subdomain or a custom domain, you don’t need to pass this value because, by default, the web browser will try to load resources from the root directory. However, if you need to publish an Angular application to a non-root location, as in the following examples, you should explicitly mention the base URL. Otherwise, the browser will not be able to load your application’s resources properly.
Learn more →yourcustomdomain.com/angularapp the base URL should be /angularapp/yourusername.github.io/myapp the base URL should be /myapp/As mentioned above, if you are deploying your application into a custom domain’s subdirectory, you have to use the subdirectory as the base URL.
Web applications usually need frequent updates, improvements, and extensions, which require changing the source codes of our applications every so often. Once we’ve completed our updates, we have to deploy our changes into GitHub Pages. We can use the main branch to maintain the source of your application. As usual, the gh-pages branch is reversed for the final static files.
As every development team does, we can set up different branches for our development requirements.
As a free service, GitHub Pages comes with some minor limitations. The static content size is limited to 1GB, so you won’t be able to upload huge media files. GitHub Pages also has a 100GB monthly bandwidth limit.
GitHub Pages doesn’t recommend its service for hosting ecommerce websites, but the tool is still great for developers looking to publish open-source web applications, such as services for developers, documentations, games, landing pages, blogs, and other types of content. If you’re looking for a slightly more robust solution stack, LAMG can help you deploy a complete single-page application into GitHub Pages with a backend for free.
Debugging Angular applications can be difficult, especially when users experience issues that are difficult to reproduce. If you’re interested in monitoring and tracking Angular state and actions for all of your users in production, try LogRocket.
LogRocket lets you replay user sessions, eliminating guesswork by showing exactly what users experienced. It captures console logs, errors, network requests, and pixel-perfect DOM recordings—compatible with all frameworks.
With Galileo AI, you can instantly identify and explain user struggles with automated monitoring of your entire product experience.
The LogRocket NgRx plugin logs Angular state and actions to the LogRocket console, giving you context around what led to an error, and what state the application was in when an issue occurred.
Modernize how you debug your Angular apps — start monitoring for free.
AI-first debugging augments traditional debugging with log clustering, pattern recognition, and faster root cause analysis. Learn where AI helps, where it fails, and how to use it safely in production.
Container queries let components respond to their own layout context instead of the viewport. This article explores how they work and where they fit alongside media queries.
React Server Components vs Islands Architecture: Learn how each reduces client JavaScript, impacts hydration and interactivity, and which trade-offs matter for production performance.
Large hosted LLMs aren’t always an option. Learn how to build agentic AI with small, local models that preserve privacy and scale.
Hey there, want to help make our blog better?
Join LogRocket’s Content Advisory Board. You’ll help inform the type of content we create and get access to exclusive meetups, social accreditation, and swag.
Sign up now
One Reply to "Deploying single-page Angular apps to GitHub Pages"
“The multiple-page approach usually works with a tightly coupled backend technology, like PHP or .NET MVC.”
That’s where you’re wrong. Both PHP and .Net MVC with Angular, Knockout, backbone, or any other UI framework and/or combination come together beautifully when each layer is crafted properly.
Not tightly coupled, and SPA with either is super easy, as long as you don’t have a web forms background about multipage applications. I did this as proof of concept and production site in 2010 – well before modern takes and frameworks on a site and had close to 100,000 concurrent viewers on the SPA watching live data, streamed from a venue in Las Vegas.
It’s 2022 SPA is not new and it’s not tightly coupled to the backend anymore than it used to be or now is.