{"id":16948,"library":"angular-cli-ghpages","title":"Angular CLI GitHub/Cloudflare Pages Deployer","description":"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.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/angular-schule/angular-cli-ghpages","tags":["javascript","angular","cli","angular-cli","ghpages","github","github pages","cloudflare pages","pages","typescript"],"install":[{"cmd":"npm install angular-cli-ghpages","lang":"bash","label":"npm"},{"cmd":"yarn add angular-cli-ghpages","lang":"bash","label":"yarn"},{"cmd":"pnpm add angular-cli-ghpages","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is an Angular CLI extension and requires @angular/cli to function as a deployment builder.","package":"@angular/cli","optional":false}],"imports":[{"note":"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.","wrong":"npm install angular-cli-ghpages","symbol":"ng add angular-cli-ghpages","correct":"ng add angular-cli-ghpages"},{"note":"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`).","wrong":"npm deploy","symbol":"ng deploy","correct":"ng deploy"},{"note":"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.","symbol":"angular.json builder configuration","correct":"{ \"builder\": \"angular-cli-ghpages:deploy\", \"options\": { ... } }"}],"quickstart":{"code":"npm install --location=global @angular/cli\nng new your-angular-project --no-standalone\ncd your-angular-project\n\ngit remote add origin https://github.com/<username>/<repositoryname>.git\n\n# Replace <username> and <repositoryname> with your GitHub details\n# Create an empty GitHub repository first for this to work.\n\nng deploy\n\n# When prompted, select 'GitHub Pages' from the options.\n# This command will build your app and deploy it to the 'gh-pages' branch.","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"all major versions"},{"fix":"Upgrade to `angular-cli-ghpages` v3.0.0 or newer to benefit from the patched `gh-pages` dependency.","message":"Versions prior to 3.0.0 used an outdated `gh-pages` dependency (older than 6.3.0) which had known security vulnerabilities.","severity":"gotcha","affected_versions":"<3.0.0"},{"fix":"Avoid using versions `1.0.1` and `1.0.2`. Upgrade to `v1.0.3` or a newer compatible version.","message":"Versions `v1.0.1` and `v1.0.2` were released with critical bugs and are known to be broken, leading to deployment failures.","severity":"gotcha","affected_versions":"1.0.1, 1.0.2"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.0.3"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `angular-cli-ghpages` deployment builder has not been correctly added to the Angular project's `angular.json` configuration.","error":"Cannot find 'deploy' target for the specified project."},{"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`).","cause":"The Angular application has not been built, or the `outputPath` configured in `angular.json` does not point to the correct build output directory.","error":"Error: Could not find a 'dist' folder to deploy."}],"ecosystem":"npm","meta_description":null}