Skip to content
:shipit: GitHub pages for angular-cli users. Publish to any gh-pages branch on GitHub (or any other branch on any other remote). Available on NPM.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci chmod +x Aug 5, 2018
.vscode uses promises for options.cname also sets up CI Aug 5, 2018
angular-testdrive uses promises for options.cname also sets up CI Aug 5, 2018
bin preparing a simple testdrive (i'm planning to add CircleCI) Aug 4, 2018
.angulardoc.json uses promises for options.cname also sets up CI Aug 5, 2018
.gitignore preparing a simple testdrive (i'm planning to add CircleCI) Aug 4, 2018
.npmignore preparing a simple testdrive (i'm planning to add CircleCI) Aug 4, 2018
LICENSE The MIT License (MIT) Nov 25, 2017
README.md Add Ionic usage info Feb 10, 2019
index.js
package-lock.json uses promises for options.cname also sets up CI Aug 5, 2018
package.json uses promises for options.cname also sets up CI Aug 5, 2018
screenshot-travis.png adds a screenshot Apr 10, 2016

README.md

angular-cli-ghpages

NPM version CircleCI


Screenshot


Publish to any gh-pages branch on GitHub (or any other branch on any other remote).
Made for angular-cli users.
Made with Travis CI, CircleCi and Co. in mind.
Brought to you by the angular.schule team!

About

This command is similar to the old github-pages:deploy command of @angular/cli which was removed in #4385. The angular-cli-ghpages command is able to push to any branch on any repository. It's made on top of tschaub/gh-pages. This script works great on Travis CI and CircleCi. No git credentials must be set up in before (use GH_TOKEN instead!). Specific environment variables of Travis-CI are evaluated, too. You will like it!

Changelog

A detailed changelog is available in the releases section.

Installation & Setup

This command has the following prerequisites:

  • Node.js 8.2.0 or higher which brings you npm 5.2.0 which brings you npx
  • Git 1.7.6 or higher
  • optional: Angular project created via angular-cli

To install the command run the following:

npm i angular-cli-ghpages --save-dev

Note: you can skip the permanent installation, too. The command npx is also able to install angular-cli-ghpages on the first usage, if you want.

Usage

Execute npx angular-cli-ghpages in order to deploy the project with a build from dist folder.
Note: you have to create the dist folder in before (e.g. ng build --prod)

Usage:

ng build --prod --base-href "https://USERNAME.github.io/REPOSITORY_NAME/"
npx angular-cli-ghpages [OPTIONS]

or

ng build --prod --base-href "/REPOSITORY_NAME/"
npx angular-cli-ghpages [OPTIONS]

or (<base href="/"> stays untouched)

ng build --prod
npx angular-cli-ghpages [OPTIONS]

If you want to push to gh-pages on the same repository with your default credentials, then just enter npx angular-cli-ghpages without any options.

Usage with Angular CLI 6 or higher

With Angular CLI 6 the build artifacts will be put in a subfolder under dist. Please take a look at the dist folder to see whether there is a subfolder with your project's name or not. If yes, you need to specify the deploy directory manually then when using this tool:

npx angular-cli-ghpages --dir=dist/[PROJECTNAME]

I most cases, the [PROJECTNAME] can be found in the angular.json file at defaultProject.

Usage with Ionic

You can use the tool with Angular based Ionic projects, too. Instead of the dist folder, the Ionic CLI will create a www folder you have to point the tool to. Just use the following commands:

ionic build --prod -- --base-href=https://USERNAME.github.io/REPOSITORY_NAME/`
npx angular-cli-ghpages --dir=www

Extra

For your convenience, the command will recognize the environment variable GH_TOKEN and will replace this pattern in the --repo string. Please do NOT disable the silent mode if you have any credentials in the repository URL! Read more about Github tokens here.

In example, the following command runs on our Travis-CI:

npx angular-cli-ghpages --repo=https://GH_TOKEN@github.com/organisation/your-repo.git --name="Displayed Username" --email=mail@example.org

You have to treat the GH_TOKEN as secure as a password!

Options

--help

  • Example: npx angular-cli-ghpages --help

Output usage information.

--version

  • Example: npx angular-cli-ghpages --version

Output the version number. Please provide the version number on any bug report!

--repo

  • optional
  • Default: url of the origin remote of the current dir (assumes a git repository)
  • Example: npx angular-cli-ghpages --repo=https://GH_TOKEN@github.com/organisation/your-repo.git

By default, gh-pages assumes that the current working directory is a git repository, and that you want to push changes to the origin remote. If instead your files are not in a git repository, or if you want to push to another repository, you can provide the repository URL in the repo option.

--message

  • optional
  • Default: Auto-generated commit
  • Example: npx angular-cli-ghpages --message="What could possibly go wrong?"

The commit message, must be wrapped in quotes.
Some handy additional text is always added, if the environment variable process.env.TRAVIS exists (for Travis CI).

--branch

  • optional
  • Default: gh-pages
  • Example: npx angular-cli-ghpages --branch=other-branch

The name of the branch you'll be pushing to. The default uses GitHub's gh-pages branch, but this can be configured to push to any branch on any remote.

--name & --email

  • optional
  • Default: value of git config user.name and git config user.email
  • Example: npx angular-cli-ghpages --name="Displayed Username" --email=mail@example.org

If you are running the command in a repository without a user.name or user.email git config properties (or on a machine without these global config properties), you must provide user info before git allows you to commit. In this case provide both name and email string values to identify the committer.

--no-silent

  • optional
  • Default: silent true (boolean)
  • Example:
    • npx angular-cli-ghpages -- Logging is in silent mode by default.
    • npx angular-cli-ghpages --no-silent -- Logging shows extended information.

Logging is in silent mode by default. In silent mode log messages are suppressed and error messages are sanitized.

The --no-silent option enables extended console logging. Keep this untouched if the repository URL or other information passed to git commands is sensitive!

WARNING: This option should kept like it is if the repository URL or other information passed to git commands is sensitive and should not be logged (== you have a public build server). By default the silent mode is enabled to avoid sensitive data exposure.

--dir

  • optional
  • Default: dist

Directory for all published sources, relative to the project-root.
Starting with Angular CLI 6 the build artifacts will be put in a subfolder under dist. Please take a look at the dist folder to see whether there is a subfolder with your project's name or not.

This option can be used to deploy completely different folders, which are not related at all to angular.

--no-dotfiles

  • optional
  • Default: dotfiles true (boolean)
  • Example:
    • npx angular-cli-ghpages -- Dotfiles are included by default.
    • npx angular-cli-ghpages --no-dotfiles -- Dotfiles are ignored.

The command includes dotfiles by default (e.g .htaccess will be committed) With --no-dotfiles files starting with . are ignored.

--dry-run

  • optional
  • Default: undefined
  • Example:
    • npx angular-cli-ghpages -- Normal behaviour: Changes are applied.
    • npx angular-cli-ghpages --dry-run -- No changes are applied at all.

Run through without making any changes. This can be very usefull, because it outputs what would happend without doing anything.

--cname

  • optional
  • Default: No CNAME file is generated
  • Example:
    • npx angular-cli-ghpages --cname=example.com

A CNAME file will be created enabling you to use a custom domain. More information on Github Pages using a custom domain.

FAQ

Before posting any issue, please read the FAQ first.

License

Code released under the MIT license.


© 2018 https://angular.schule

You can’t perform that action at this time.