Vite plugin to publish your app to GitHub Pages
npm install vite-plugin-gh-pages> Vite plugin to publish your app to GitHub Pages.
This plugin uses gh-pages to publish your app to GitHub Pages when running vite build.
- 🚀 Zero-config deployment to GitHub Pages
- 🎯 Automatic base URL configuration from package name
- ⚡️ Lifecycle hooks for custom deployment logic
- 📄 Preserves dotfiles and adds .nojekyll by default
- 🔄 Customizable branch and commit options
``bashNPM
npm i -D vite-plugin-gh-pages
Usage
Vite requires a public base path for your app to work on GitHub Pages.
For example, if your repository name is "repo-name,"
base should be /repo-name/.`js
// vite.config.js
import { ghPages } from "vite-plugin-gh-pages";/* @type {import('vite').UserConfig} /
export default {
base: "/repo-name/",
plugins: [ghPages()],
};
`If no value for
base is specified, the plugin will attempt to infer the value using the value of package.json#name.`js
// package.json
{
"name": "repo-name", // base can be omitted if name is specified
"scripts": {
"dev": "vite",
"build": "vite build"
}
}
`Options
Additional plugin options are passed to
gh-pages. All options from the gh-pages package are supported, plus additional lifecycle hooks.`js
ghPages({
branch: "docs",
message: "Custom deploy message",
});
`API
`ts
interface GhPagesOptions {
/**
* Specify the branch to push to.
* @default "gh-pages"
*/
branch?: string; /**
* Destination folder in the publish branch.
* @default "."
*/
dest?: string;
/**
* Add files, never remove existing ones.
* @default false
*/
add?: boolean;
/**
* Callback called before
git add.
* @default null;
*/
beforeAdd?: null | Function; /**
*
true by default for .nojekyll to be included.
* @default true
*/
dotfiles?: boolean; /**
* Path to your Git executable.
* @default "git"
*/
git?: string;
/**
* Commit message for all commits.
* @default "Updates"
*/
message?: string;
/**
* Use
remove instead.
* @deprecate
*/
only?: string; /**
* Push branch to remote.
* Set to
false to commit without pushing.
* @default true
*/
push?: boolean; /**
* Force push new commit without parent history.
* @default true
*/
history?: boolean;
/**
* Name of the remote to push to.
* @default "origin"
*/
remote?: string;
/**
* Removes files that match the given pattern.
* @default "."
*/
remove?: string;
/**
* URL for the remote origin of the git repository.
* @default [current remote URL]
*/
repo?: string;
/**
* Avoid showing repository URLs or other information in errors.
* @default false
*/
silent?: boolean;
/**
* Select files to be published that match the given pattern.
@default "\/"
*/
src?: string | string[];
/**
* Create a tag after committing changes on the target branch.
* @default ""
*/
tag?: string;
/**
* Git user metadata.
* Required for Git to commit.
* @default null
*/
user?: null | {
name: string;
email: string;
};
}
`Lifecycle Hooks
$3
Called before publishing to GitHub Pages. Useful for writing additional files to the
outDir.`js
import fs from "node:fs";
import path from "node:path";
import { ghPages } from "vite-plugin-gh-pages";/* @type {import('vite').UserConfig} /
export default {
plugins: [
ghPages({
/* @type {options: GhPagesOptions & { outDir: string } => void} /
onBeforePublish: (options) => {
const CNAME = path.join(options.outDir, "CNAME");
fs.writeFileSync(CNAME, "example.com");
},
}),
],
};
`$3
Called after successful deployment to GitHub Pages.
`js
ghPages({
/* @type {options: GhPagesOptions & { outDir: string } => void} /
onPublish: (options) => {
console.log(🎉 Successfully deployed to ${options.branch}!);
},
});
`$3
Called if a publishing error occurs.
`js
ghPages({
/ @type {(error: any) => void} /
onError: (error) => {
console.error("Deployment failed:", error);
process.exit(1);
},
});
`Examples
$3
`js
ghPages({
branch: "production",
onBeforePublish: ({ outDir }) => {
fs.writeFileSync(path.join(outDir, "CNAME"), "mysite.com");
},
});
`$3
`js
ghPages({
onBeforePublish: ({ outDir }) => {
console.log(📦 Starting deployment from ${outDir}...);
},
onPublish: ({ branch }) => {
console.log(🎉 Successfully deployed to ${branch}!);
},
onError: (error) => {
console.error("❌ Deployment failed:", error);
},
});
``