gh-pages

repository·main·Indexed 25 days ago

A utility for publishing files to a gh-pages branch on GitHub or any other Git remote. It automates cloning, committing, and pushing build artifacts via a Node.js API or CLI. Version 6.3.0 requires Git >= 1.9 and Node > 14.

Tokens: 3.1K
Snippets: 7
Records: 18
Agent score: 84%

What's inside gh-pages

Deploy to GitHub Pages using GitHub Actions

main

To deploy via GitHub Actions, you must set the git remote URL using the GITHUB_TOKEN and define a user with the -u flag. The GITHUB_TOKEN and GITHUB_REPOSITORY variables are provided automatically by GitHub Actions and should be passed to the environment.

If you are using a named script from package.json (e.g., npm run deploy), you must use the -- separator to pass arguments through to the underlying gh-pages command.

# Example: Direct deployment
- name: Deploy with gh-pages
  run: |
    git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
    npx gh-pages -d build -u "github-actions-bot <support+actions@github.com>"
   env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# Example: Deployment via npm script (e.g., "deploy": "gh-pages -d build")
- name: Deploy with gh-pages
  run: |
    git remote set-url origin https://git:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
    npm run deploy -- -u "github-actions-bot <support+actions@github.com>"
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Deploy to GitHub Pages with a custom domain
main
Use the --cname option to automatically create a CNAME file containing your custom domain name during deployment.
```
gh-pages -d build --cname custom-domain.com
```
https://github.com/tschaub/gh-pages/blob/main/readme.md
Configure asset paths for GitHub Pages Project Sites
main
When hosting on a GitHub Project Site (e.g., username.github.io/repo-name/), assets may fail to load with 404 errors if paths are absolute. You must configure your build tool to use relative paths or a specific base path:
- Create React App: Set the "homepage" property in package.json.
- Vite: Set the "base" property in vite.config.js.
- Next.js: Set the "basePath" property in next.config.js.
https://github.com/tschaub/gh-pages/blob/main/readme.md
Install gh-pages
main
Install gh-pages as a development dependency using npm. This module requires Git >= 1.9 and Node > 14.
```
npm install gh-pages --save-dev
```
https://github.com/tschaub/gh-pages/blob/main/readme.md
Configure the `gh-pages` cache directory
main
The gh-pages module writes temporary files to node_modules/.cache/gh-pages. You can customize this location by setting the CACHE_DIR environment variable.
https://github.com/tschaub/gh-pages/blob/main/readme.md
Debug `gh-pages` output
main
To see additional debug output from the script, set the NODE_DEBUG environment variable to gh-pages before running your command.
```
NODE_DEBUG=gh-pages npm run deploy
```
https://github.com/tschaub/gh-pages/blob/main/readme.md
Resolve `branch already exists` error
main
If you encounter the error fatal: A branch named 'gh-pages' already exists., it is often due to a corrupted or existing cache. You can resolve this by manually cleaning the cache directory.
You can either run the provided clean script or manually delete the directory:
https://github.com/tschaub/gh-pages/blob/main/readme.md
Use the `publish` API
main
The publish function creates a temporary clone of the current repository, creates a branch (defaulting to gh-pages), copies files from the specified directory, commits them, and pushes to the remote.
Warning: By default, any files in the target branch that are not in the source directory will be removed. To prevent this, use the add: true option.
https://github.com/tschaub/gh-pages/blob/main/readme.md
Configure ESLint using eslint-config-tschaub
main
To use the pre-defined ESLint configurations from this project, import configs from eslint-config-tschaub in your eslint.config.mjs file and spread them into the default export array.
```
import configs from 'eslint-config-tschaub';

export default [...configs];
```
https://github.com/tschaub/gh-pages/blob/main/eslint.config.mjs

Configure `publish` options

main

The publish method accepts an optional options object to customize the deployment behavior:

Option	Type	Default	Description
`src`	`string\|Array<string>`	`'*/'`	Minimatch pattern(s) to select files to publish.
`branch`	`string`	`'gh-pages'`	The name of the branch to push to. Use `-b \| --branch` in CLI.
`dest`	`string`	`'.'`	The destination folder within the target branch.
`dotfiles`	`boolean`	`false`	If `true`, includes files starting with `.` (dotfiles).
`nojekyll`	`boolean`	`false`	If `true`, writes a `.nojekyll` file to bypass Jekyll on GitHub Pages.
`cname`	`string`	`undefined`	Writes a `CNAME` file with the provided custom domain name.
`add`	`boolean`	`false`	If `true`, only adds files and never removes existing files in the target branch.
`repo`	`string`	`origin URL`	The repository URL to push to. Use `-r \| --repo` in CLI.
`remote`	`string`	`'origin'`	The name of the remote to push to.
`tag`	`string`	`''`	Creates a git tag with this name after committing.
`message`	`string`	`'Updates'`	The commit message used for the changes.
`user`	`Object`	`null`	Object with `{ name, email }` for git commits if not configured globally.
`remove`	`string`	`'*/'`	Pattern of files to remove in the target branch (ignored if `add: true` is set).
`push`	`boolean`	`true`	If `false`, only commits changes without pushing to remote.
`history`	`boolean`	`true`	If `false`, pushes a force new commit without parent history.
`silent`	`boolean`	`false`	If `true`, avoids showing repository URLs in error messages.
`beforeAdd`	`function`	`null`	Async callback executed right before `git add`. Receives `git` object.
`git`	`string`	`'git'`	Path to the `git` executable.

Use the `gh-pages` CLI
main
The gh-pages package provides a command line utility. You can use it directly or via npm scripts.
To deploy a dist folder using an npm script, add the following to your package.json:
```
"scripts": {
  "deploy": "gh-pages -d dist"
}
```
Then run:
```
npm run deploy
```
https://github.com/tschaub/gh-pages/blob/main/readme.md
Clean the gh-pages cache directory
main
The clean() method removes the entire cache directory used by gh-pages to prevent conflicts or corrupted states during the publishing process.
https://github.com/tschaub/gh-pages/blob/main/lib/index.js