mitrenuxt-github-pages
Nuxt module to fix trailing slash issues when deploying to GitHub Pages. This module ensures your static Nuxt site works correctly with GitHub Pages' file resolution behavior.
The Problem
When deploying a Nuxt 3 static site to GitHub Pages:
- Visiting
/docs/pageworks fine initially - But refreshing the page or directly visiting
/docs/page/returns a 404 error - This happens because Nuxt generates
/docs/page.htmlbut GitHub Pages expects/docs/page/index.html
The Solution
This module automatically creates duplicate HTML files during the build process. For every /path/index.html, it creates a /path.html file, ensuring URLs work with or without trailing slashes.
Features
- 🚀 Zero configuration required
- 🎯 Works with both GitHub Pages and Netlify
- 📦 Lightweight with no runtime overhead
- 🔧 Configurable output directories
- 📝 TypeScript support
- 🪵 Optional verbose logging
- 🔍 SEO-friendly with automatic canonical URLs
Quick Setup
Installation
# npm
npm install nuxt-github-pages
# pnpm
pnpm add nuxt-github-pages
# yarn
yarn add nuxt-github-pages
# bun
bun add nuxt-github-pagesConfiguration
Add nuxt-github-pages to the modules section of nuxt.config.ts:
export default defineNuxtConfig({
modules: ['nuxt-github-pages']
})That's it! The module will automatically run during nuxt generate.
Options
You can configure the module by adding options:
export default defineNuxtConfig({
modules: ['nuxt-github-pages'],
githubPages: {
// Enable or disable the module (default: true)
enabled: true,
// Directories to check for output files (default: ['dist', '.output/public'])
outputDirs: ['dist', '.output/public'],
// Show verbose logging (default: true)
verbose: true,
// Add canonical URLs to prevent duplicate content SEO issues (default: true)
canonicalUrls: true,
// Use trailing slashes in canonical URLs (default: false)
trailingSlash: false,
// Create duplicate HTML files to avoid redirects (default: true)
createDuplicates: true
}
})Option Details
enabled
- Type:
boolean - Default:
true - Description: Enable or disable the module. Useful for conditional builds.
outputDirs
- Type:
string[] - Default:
['dist', '.output/public'] - Description: Array of directories to check for generated files. The module will use the first directory that exists.
verbose
- Type:
boolean - Default:
true - Description: Show detailed logging during the build process.
canonicalUrls
- Type:
boolean - Default:
true - Description: Automatically inject canonical URLs into all HTML files to prevent duplicate content SEO issues. The canonical URL tells search engines which version of the page is preferred.
trailingSlash
- Type:
boolean - Default:
false - Description: Whether to use trailing slashes in canonical URLs. When
false, canonical URLs will be/path. Whentrue, they will be/path/. Choose based on your site's URL structure preference.
createDuplicates
- Type:
boolean - Default:
true - Description: Create duplicate HTML files to fix GitHub Pages routing. When
true, creates both/path/index.htmland/path.html. Set tofalseif you only need canonical URLs without file duplication (e.g., for other hosting platforms or if you handle redirects differently).
⚠️ Warning: Setting this to false will cause 404 errors on GitHub Pages for URLs without trailing slashes.
How It Works
- During the
nuxt generatebuild process, this module hooks into theprerender:doneevent - It scans the output directory for all
index.htmlfiles - For each
index.htmlfound at/path/to/page/index.html, it creates a duplicate at/path/to/page.html - Optionally injects canonical URLs into all HTML files to prevent SEO duplicate content issues
- This ensures both
/path/to/pageand/path/to/page/resolve correctly on GitHub Pages
Example
Given this generated structure:
dist/
├── index.html
├── about/
│ └── index.html
├── docs/
│ ├── index.html
│ └── getting-started/
│ └── index.htmlThe module creates these additional files:
dist/
├── about.html ← Created
├── docs.html ← Created
├── docs/
│ └── getting-started.html ← CreatedDeployment
After building with nuxt generate, deploy the output directory to GitHub Pages as usual:
# Build your site
pnpm run generate
# Deploy to GitHub Pages (example using gh-pages)
npx gh-pages -d distCompatibility
- ✅ Nuxt 3.0+
- ✅ GitHub Pages
- ✅ Netlify
- ✅ Any static hosting that serves
.htmlfiles
Why Not Use Other Solutions?
Post-build Scripts
While you could use a custom post-build script, this module:
- Integrates seamlessly with Nuxt's build process
- Provides proper error handling and logging
- Works with any package manager without extra configuration
- Is reusable across projects
Netlify Redirects
Netlify-specific _redirects only work on Netlify. This module works everywhere.
.htaccess or nginx
These require server configuration access, which you don't have with GitHub Pages.
Development
Releasing New Versions
We use GitHub Actions for all production releases to ensure consistency and security.
Option 1: Manual Release (Recommended)
# Using our convenience script
./scripts/release-prod.sh patch # For bug fixes
./scripts/release-prod.sh minor # For new features
./scripts/release-prod.sh major # For breaking changes
# Or directly with GitHub CLI
gh workflow run release.yml --field version_type=patch --field create_github_release=trueOption 2: Automated PR Release
Add a release label to your PR before merging:
release:patch- Bug fixesrelease:minor- New featuresrelease:major- Breaking changes
The release will trigger automatically when the PR is merged.
Local Development
# Test the release process without making changes
./scripts/release.sh patch --dry-run
# After a release, always sync your local repository
git pull origin main --tagsFor more details, see CONTRIBUTING.md.
SEO Considerations
By default, this module injects canonical URLs to prevent duplicate content issues. Both /path and /path/ will point to the same canonical URL, telling search engines which version is preferred.
<!-- Both pages will have the same canonical URL -->
<!-- Default (trailingSlash: false): -->
<link rel="canonical" href="/about">
<!-- With trailingSlash: true: -->
<link rel="canonical" href="/about/">You can customize this behavior:
export default defineNuxtConfig({
modules: ['nuxt-github-pages'],
githubPages: {
// Disable canonical URLs entirely
canonicalUrls: false,
// Or use trailing slashes in canonical URLs
trailingSlash: true // Results in href="/path/"
}
})Recommended Configurations by Platform
These recommendations are based on the excellent Trailing Slash Guide by Sébastien Lorber, which provides comprehensive testing and documentation of trailing slash behavior across all major hosting platforms. If you're dealing with trailing slash issues, his guide is an invaluable resource.
GitHub Pages
GitHub Pages redirects /about to /about/ on refresh, indicating it prefers trailing slashes:
export default defineNuxtConfig({
modules: ['nuxt-github-pages'],
githubPages: {
canonicalUrls: true,
trailingSlash: true // URLs like /about/ (with trailing slash)
}
})Netlify
Netlify's "Pretty URLs" feature (enabled by default) prefers trailing slashes for directory-based content:
export default defineNuxtConfig({
modules: ['nuxt-github-pages'],
githubPages: {
canonicalUrls: true,
trailingSlash: true // URLs like /about/ (with trailing slash)
}
})Cloudflare Pages
Cloudflare Pages automatically adds trailing slashes and creates redirects:
export default defineNuxtConfig({
modules: ['nuxt-github-pages'],
githubPages: {
canonicalUrls: true,
trailingSlash: true // URLs like /about/ (with trailing slash)
}
})Vercel
Vercel is configurable but defaults to no trailing slashes:
export default defineNuxtConfig({
modules: ['nuxt-github-pages'],
githubPages: {
canonicalUrls: true,
trailingSlash: false // URLs like /about (no trailing slash)
}
})Disable Canonical URLs
If you're managing canonical URLs through other means (like useHead or SEO modules):
export default defineNuxtConfig({
modules: ['nuxt-github-pages'],
githubPages: {
canonicalUrls: false // Don't inject any canonical URLs
}
})Troubleshooting
Module doesn't seem to run
- Ensure you're using
nuxt generate(notnuxt build) - Check that your
nitro.presetis set to'static'(this is the default fornuxt generate) - Look for log messages in your build output
Files aren't being created
- Verify your output directory matches one in
outputDirs - Enable
verbose: trueto see detailed logging - Ensure your build is completing successfully
Custom output directory
If you use a custom output directory, add it to the configuration:
export default defineNuxtConfig({
modules: ['nuxt-github-pages'],
githubPages: {
outputDirs: ['my-custom-dist', 'dist', '.output/public']
}
})Testing
# Run tests
pnpm run test
# Run tests in watch mode
pnpm run test:watchSee test/README.md for detailed information about the testing approach and patterns used in this module.
See test/TEST_MATRIX.md for current test coverage.
Contributing
We welcome contributions! Please see our Contributing Guide for details on:
- Development setup and workflow
- Automated quality checks (git hooks)
- Testing guidelines
- Pull request process
- Coding standards
Quick Start for Contributors
# Setup
pnpm install
pnpm run dev:prepare
# Before committing
pnpm run test:allCI/CD Process
This project uses GitHub Actions for continuous integration and deployment:
- CI: Runs on every push and PR (linting, type checking, tests, security)
- Release: Manual workflow for creating releases (version bump, npm publish, GitHub release)
- Auto Release: PRs with
release:patch,release:minor, orrelease:majorlabels trigger automatic releases when merged
See .github/SETUP.md for workflow configuration details.
Development
# Install dependencies
pnpm install
# Generate type stubs
pnpm run dev:prepare
# Develop with the playground
pnpm run dev
# Build the playground
pnpm run dev:build
# Run ESLint
pnpm run lint
# Run type checking
pnpm run test:types
# Clean build artifacts
pnpm run clean
# Run ALL checks (recommended before committing)
pnpm run test:all
# Release new version
pnpm run releaseDevelopment Workflow
- Before starting work: Run
pnpm installandpnpm run dev:prepare - During development: Use
pnpm run devto test changes in the playground - Before committing: Run
pnpm run test:allto ensure everything passes - After testing: Run
pnpm run cleanto remove build artifacts
Automated Quality Checks
This project uses git hooks to maintain code quality:
- Pre-commit hook: Automatically runs ESLint on staged files and fixes issues
- Automatic formatting: Code style issues are fixed automatically on commit
- Files are linted and formatted using the Nuxt ESLint configuration
Development Scripts
pnpm run test:all- Complete test suite (install → prepare → test → lint → type check → clean)pnpm run clean- Remove all build artifacts (preserves node_modules)./scripts/pre-release.sh- Run all checks and build before releasing
Development Tips
- The playground directory is for testing during development
- Test fixtures are automatically cleaned during test runs
- Build artifacts (.nuxt, .output, dist) are git-ignored
- Always run
pnpm run test:allbefore pushing changes
License
See NOTICE.md for additional copyright and license information.
Security
For security issues, please see our Security Policy.
Code of Conduct
This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.
Credits
This module was created to solve the long-standing trailing slash issue when deploying Nuxt sites to GitHub Pages.
Created by MITRE for the open source community.