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.
Benefits of GitHub Pages
Moreover, GitHub Pages offers you a free
github.io subdomain. If you have a domain name already, you can easily use that as well.
Creating a single-page application with Angular
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.
Deploying your Angular app into GitHub Pages
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:
When to pass a base URL
--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.
yourcustomdomain.com/angularappthe base URL should be
yourusername.github.io/myappthe base URL should be
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.
Building your development workflow
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.
Limitations and conclusions
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.
Experience your Angular apps exactly how a user doesDebugging 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. https://logrocket.com/signup/
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.
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.