vite-plugin-gh-pages

1.0.1 verified Mon Apr 27 auth: no javascript

Vite plugin (v1.0.1) for zero-config deployment to GitHub Pages. Leverages the gh-pages package to publish built output to a branch (default: gh-pages) with automatic base URL inference from package.json#name. Includes lifecycle hooks (onBeforePublish, onPublish, onError) and sensible defaults (preserves dotfiles, adds .nojekyll). Active maintenance, ships TypeScript types, and supports all gh-pages options. Differentiator: first-class Vite integration vs manual gh-pages scripts.

Common errors

error Cannot find module 'vite-plugin-gh-pages' or its corresponding type declarations. ↓

cause Package not installed or TypeScript cannot resolve types.

fix

npm install --save-dev vite-plugin-gh-pages. Ensure tsconfig includes node_modules/@types or skipLibCheck.

error Error: GitHub Pages publish failed: No such remote 'origin' ↓

cause Git remote named 'origin' not found in local repository.

fix

Add a remote: 'git remote add origin git@github.com:user/repo.git' or set remote option to an existing remote name.

error Uncaught TypeError: (0 , vite_plugin_gh_pages.ghPages) is not a function ↓

cause Using default import instead of named import.

fix

Change to import { ghPages } from 'vite-plugin-gh-pages'.

Warnings

breaking Upgrade from v0.x to v1.0: gh-pages dependency upgraded from 4.0.0 to 6.0.0. Check gh-pages changelog for breaking changes. ↓

fix Review gh-pages v6 release notes; update plugin options if using removed features like `only` (deprecated).

gotcha Automatic base detection from package.json#name only works if package name matches repository name (e.g., 'my-repo' => base '/my-repo/'). Otherwise, you must set base manually. ↓

fix Set base explicitly in vite.config: base: '/your-repo-name/'

gotcha Plugin uses `enforce: 'post'` to run after Vite build plugins. If you have other post plugins, ordering may be affected. ↓

fix Ensure no other `enforce: 'post'` plugins conflict; order within plugins array matters.

gotcha The `onPublish` callback overrides the default console messages. If you supply onPublish, no default success message is printed. ↓

fix If you want both default and custom messages, call the default logic inside your callback or omit onPublish.

deprecated Option `only` is deprecated by gh-pages in favor of `remove`. This plugin passes options through without deprecation warnings. ↓

fix Use `remove` instead of `only` when specifying patterns to remove.

Install

npm install vite-plugin-gh-pages

yarn add vite-plugin-gh-pages

pnpm add vite-plugin-gh-pages

Imports

ghPages
wrong
```
const ghPages = require('vite-plugin-gh-pages')
```
correct
```
import { ghPages } from 'vite-plugin-gh-pages'
```
Named export only. Plugin is ESM; commonjs require will not work without dynamic import.
GhPagesOptions
```
import type { GhPagesOptions } from 'vite-plugin-gh-pages'
```
TypeScript users: this type is exported for custom callback typing.

Plugin (default)

wrong

import ghPages from 'vite-plugin-gh-pages'

correct

import { ghPages } from 'vite-plugin-gh-pages'

There is no default export. Always use named import { ghPages }.

Quickstart

Configure Vite with ghPages plugin, setting base path and custom deploy message with lifecycle hook.

// vite.config.ts
import { defineConfig } from 'vite';
import { ghPages } from 'vite-plugin-gh-pages';

export default defineConfig({
  base: '/my-repo/',
  plugins: [
    ghPages({
      branch: 'gh-pages',
      message: 'Deploy v' + process.env.npm_package_version ?? 'latest',
      onBeforePublish: (options) => {
        console.log('Publishing from', options.outDir);
      },
    }),
  ],
});