How to Deploy an Angular 18 App on GitHub Pages

Introduction

Deploying your Angular 18 application on GitHub Pages is a convenient and cost-effective way to showcase your work to the world. While there are numerous resources available for deploying older versions of Angular, Angular 17 and 18 introduced some structural changes that render many of those guides obsolete.

After a lot of trial and error, I developed a streamlined process that automates the deployment with the necessary customizations.

This guide will walk you through the process, ensuring that your application is successfully deployed and accessible to anyone with a web browser.

Step 1: Install the Deployment Tool

First, install the angular-cli-ghpages package, which will help automate the deployment process:

npm install --save-dev angular-cli-ghpages        

Step 2: Update angular.json

Next, update your angular.json file to specify the build output directory and the deployment configuration:

The outputPath specifies where the Angular CLI will place the production bundle after building your application.

{
  "architect": {
    "build": {
      "options": {
        "outputPath": "dist/<app-name>"               // Specify the output directory
      }
    },
    "deploy": {
      "builder": "angular-cli-ghpages:deploy",
      "options": {
        "repo": "https://github.com/<username>/<repo-name>.git",
        "branch": "gh-pages",
        "dir": "dist/<app-name>/browser"          // Specify the build path for deployment
      }
    }
  }
}        

Replace <app-name>, <username>, and <repo-name> with your actual application name, GitHub username, and repository name, respectively.

The dir option in the deploy section specifies where to find the index.html file and other build artifacts for deployment.

In Angular 18, the build artifacts are often located in dist/<app-name>/browser.

See an example of angular.json

Step 3: Modify package.json

In your package.json, add or modify the build and deploy scripts to include the base href and to use the Angular CLI’s deployment command:

{
  "scripts": {
    "build": "ng build --base-href /<repo-name>/",
    "deploy": "ng deploy"
  }
}        

Replace <repo-name> with the name of your GitHub repository.

Step 4: Configure Hash-Based Routing (Optional)

To ensure proper routing when deploying on GitHub Pages, which serves static files and may not handle client-side routing correctly, use hash-based routing:

• Update app.config.ts: (since we are standalone )

import {HashLocationStrategy, LocationStrategy} from "@angular/common";

export const appConfig: ApplicationConfig = {
  providers: [
   /* other */
    {provide:LocationStrategy,useClass:HashLocationStrategy}
  ]};
        

Step 5: Build and Deploy

Finally, you can build and deploy your Angular app with just two commands:

npm run build        

npm run deploy        

Step 6 : one time configuration

To complete the setup, configure GitHub Pages for your repository:

1. Navigate to Your GitHub Repository: Go to your repository on GitHub.
2. Access Repository Settings: Click on the "Settings" tab.
3. Configure GitHub Pages: select for the source Deploy from a branch ,and the branch gh-pages
4. Trigger Deployment: Once configured, the deployment will begin automatically. You can monitor the deployment progress in the "Actions" tab of your repository.
5. Access Your Deployed App: After the deployment process is complete, you can access your deployed application at https://<username>.github.io/<repo-name>/.

Conclusion

With this automated approach, deploying an Angular 18 app to GitHub Pages becomes a seamless process, thanks to the angular-cli-ghpages tool and the customized configuration. This method not only saves time but also ensures that your app is correctly deployed with minimal manual intervention.