{"id":22675,"library":"vite-plugin-gh-pages","title":"vite-plugin-gh-pages","description":"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.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/metonym/vite-plugin-gh-pages","tags":["javascript","vite plugin","gh-pages","GitHub Pages","typescript"],"install":[{"cmd":"npm install vite-plugin-gh-pages","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-gh-pages","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-gh-pages","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core publishing mechanism","package":"gh-pages","optional":false}],"imports":[{"note":"Named export only. Plugin is ESM; commonjs require will not work without dynamic import.","wrong":"const ghPages = require('vite-plugin-gh-pages')","symbol":"ghPages","correct":"import { ghPages } from 'vite-plugin-gh-pages'"},{"note":"TypeScript users: this type is exported for custom callback typing.","symbol":"GhPagesOptions","correct":"import type { GhPagesOptions } from 'vite-plugin-gh-pages'"},{"note":"There is no default export. Always use named import { ghPages }.","wrong":"import ghPages from 'vite-plugin-gh-pages'","symbol":"Plugin (default)","correct":"import { ghPages } from 'vite-plugin-gh-pages'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport { ghPages } from 'vite-plugin-gh-pages';\n\nexport default defineConfig({\n  base: '/my-repo/',\n  plugins: [\n    ghPages({\n      branch: 'gh-pages',\n      message: 'Deploy v' + process.env.npm_package_version ?? 'latest',\n      onBeforePublish: (options) => {\n        console.log('Publishing from', options.outDir);\n      },\n    }),\n  ],\n});","lang":"typescript","description":"Configure Vite with ghPages plugin, setting base path and custom deploy message with lifecycle hook."},"warnings":[{"fix":"Review gh-pages v6 release notes; update plugin options if using removed features like `only` (deprecated).","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Set base explicitly in vite.config: base: '/your-repo-name/'","message":"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.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Ensure no other `enforce: 'post'` plugins conflict; order within plugins array matters.","message":"Plugin uses `enforce: 'post'` to run after Vite build plugins. If you have other post plugins, ordering may be affected.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"If you want both default and custom messages, call the default logic inside your callback or omit onPublish.","message":"The `onPublish` callback overrides the default console messages. If you supply onPublish, no default success message is printed.","severity":"gotcha","affected_versions":">=0.3.0"},{"fix":"Use `remove` instead of `only` when specifying patterns to remove.","message":"Option `only` is deprecated by gh-pages in favor of `remove`. This plugin passes options through without deprecation warnings.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"npm install --save-dev vite-plugin-gh-pages. Ensure tsconfig includes node_modules/@types or skipLibCheck.","cause":"Package not installed or TypeScript cannot resolve types.","error":"Cannot find module 'vite-plugin-gh-pages' or its corresponding type declarations."},{"fix":"Add a remote: 'git remote add origin git@github.com:user/repo.git' or set `remote` option to an existing remote name.","cause":"Git remote named 'origin' not found in local repository.","error":"Error: GitHub Pages publish failed: No such remote 'origin'"},{"fix":"Change to `import { ghPages } from 'vite-plugin-gh-pages'`.","cause":"Using default import instead of named import.","error":"Uncaught TypeError: (0 , vite_plugin_gh_pages.ghPages) is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}