Registry / devops / vite-plugin-gh-pages

vite-plugin-gh-pages

library1.0.1jsnpmunverified

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.

devops http-networking

npm install vite-plugin-gh-pages

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-GH-PAG

vite-plugin-gh-pages

devopsjavascriptv1.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ghPages

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

✗ const ghPages = require('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)

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

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

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

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); }, }), ], });

Debug

Known issues

breakingUpgrade 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).

affects: <1.0.0

gotchaAutomatic 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/'

affects: >=0.3.0

gotchaPlugin 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.

affects: >=0.3.0

gotchaThe `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.

affects: >=0.3.0

deprecatedOption `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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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: GitHub Pages publish failed: No such remote 'origin'

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.

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

Using default import instead of named import.

fix

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

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

gh-pagesrequiredCore publishing mechanism

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/metonym/vite-plugin-gh-pages ↗

packagehttps://www.npmjs.com/package/vite-plugin-gh-pages ↗