Angular CLI GitHub/Cloudflare Pages Deployer

3.0.2 · active · verified Wed Apr 22

angular-cli-ghpages is an Angular CLI extension that streamlines the deployment of Angular applications to static hosting platforms like GitHub Pages and Cloudflare Pages. It integrates directly with the Angular CLI's `ng deploy` command, automating the build process, committing the compiled output to a specified Git branch (commonly `gh-pages`), and pushing it to a remote repository. The current stable version is 3.0.2, which supports Angular CLI 18 and newer. New major versions are typically released in sync with Angular's major releases to ensure compatibility. Its key differentiator is its seamless integration with the Angular development workflow, abstracting away manual Git operations and build output management for deployment.

Common errors

```
Cannot find 'deploy' target for the specified project.
```
cause The `angular-cli-ghpages` deployment builder has not been correctly added to the Angular project's `angular.json` configuration.

fix Run `ng add angular-cli-ghpages` in your project's root directory to integrate the deployment builder. This command will update your `angular.json` automatically.
```
Error: Could not find a 'dist' folder to deploy.
```
cause The Angular application has not been built, or the `outputPath` configured in `angular.json` does not point to the correct build output directory.

fix Ensure your Angular project builds successfully by running `ng build`. If you have multiple build configurations, specify the correct target using `--build-target` (e.g., `ng deploy --build-target production`).

Warnings

breaking Major versions of `angular-cli-ghpages` are tightly coupled to specific Angular CLI versions. Version 3.x requires Angular CLI 18+, Version 2.x supports Angular CLI 17-18, and Version 1.x supports Angular CLI 13-16.
Fix: Always ensure your `angular-cli-ghpages` version matches your Angular CLI version, as documented in the package's release notes. Upgrade your Angular project or use a compatible older version of this package.
gotcha Versions prior to 3.0.0 used an outdated `gh-pages` dependency (older than 6.3.0) which had known security vulnerabilities.
Fix: Upgrade to `angular-cli-ghpages` v3.0.0 or newer to benefit from the patched `gh-pages` dependency.
gotcha Versions `v1.0.1` and `v1.0.2` were released with critical bugs and are known to be broken, leading to deployment failures.
Fix: Avoid using versions `1.0.1` and `1.0.2`. Upgrade to `v1.0.3` or a newer compatible version.
breaking Starting from v2.0.0, the default deployment behavior is to remove existing files in the target branch (`gh-pages`) before adding new ones. This can lead to loss of custom files not part of your build output.
Fix: If you need to preserve existing files on your `gh-pages` branch, use the `--add` option with your `ng deploy` command: `ng deploy --add`.
gotcha The `remote` option in versions prior to `v2.0.3` could cause deployment issues if not explicitly provided, failing to identify the Git remote to push to.
Fix: If experiencing deployment issues with older versions, explicitly provide the `--remote` option (e.g., `ng deploy --remote origin`), or upgrade to `v2.0.3` or newer which provides a default value.

Install

npm install angular-cli-ghpages npm
yarn add angular-cli-ghpages yarn
pnpm add angular-cli-ghpages pnpm

Imports

ng add angular-cli-ghpages
wrong:
```
npm install angular-cli-ghpages
```
correct:
```
ng add angular-cli-ghpages
```
This command integrates the `angular-cli-ghpages` deployment builder into your Angular project, configuring `angular.json` and installing necessary packages. It is the primary way to 'add' this functionality to your project.
ng deploy
wrong:
```
npm deploy
```
correct:
```
ng deploy
```
After installation via `ng add`, this command executes the full build and deployment process to GitHub Pages or a specified remote. It accepts various options (e.g., `--branch`, `--message`).
angular.json builder configuration
```
{ "builder": "angular-cli-ghpages:deploy", "options": { ... } }
```
While not a direct code import, this is the configuration 'symbol' that defines how `ng deploy` uses the `angular-cli-ghpages` builder within your `angular.json` project's `architect` section. It is typically managed automatically by `ng add` but can be manually adjusted for advanced settings.

Quickstart

Demonstrates how to install the Angular CLI, create a new project, link it to a GitHub repository, and deploy it to GitHub Pages using the `ng deploy` command.

npm install --location=global @angular/cli
ng new your-angular-project --no-standalone
cd your-angular-project

git remote add origin https://github.com/<username>/<repositoryname>.git

# Replace <username> and <repositoryname> with your GitHub details
# Create an empty GitHub repository first for this to work.

ng deploy

# When prompted, select 'GitHub Pages' from the options.
# This command will build your app and deploy it to the 'gh-pages' branch.

view raw JSON →