Deploying single-page Angular apps to GitHub Pages

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

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.

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.

---

Over 200k developers use LogRocket to create better digital experiences

Learn more →

---

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&gt;.github.io/<repositoryname> . You can see that the example application I created is live:

When to pass a base URL

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.

• For yourcustomdomain.com/angularapp the base URL should be /angularapp/
• For 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.

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 does

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. https://logrocket.com/signup/

LogRocket is like a DVR for web and mobile apps, recording literally everything that happens on your site including network requests, JavaScript errors, and much more. Instead of guessing why problems happen, you can aggregate and report on what state your application was in when an issue occurred.

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.