Nuxt3 Ghpages

Nuxt3 Ghpages is a boilerplate template for deploying a Nuxt3 application to GitHub Pages using the gh-pages library. It packages a minimal Nuxt3 app with a single npm run deploy script that static-generates the site and pushes it to the gh-pages branch, so GitHub Pages can serve it without extra CI configuration.

What is Nuxt3 Ghpages?

Nuxt3 Ghpages is a starter template by dariotecchia that demonstrates how to publish a Nuxt3 app on GitHub Pages. The input is a standard Nuxt3 project, and the output is a static site hosted under https://dariotecchia.github.io/nuxt3-ghpages/. The template relies on nuxt generate to pre-render pages into .output/public and on the gh-pages library to commit that directory to the gh-pages branch. It runs on any machine with Node.js and npm, and the deployment target is GitHub Pages.

Key Features

• Nuxt3 and Vue3 — The app is built on Nuxt3, the SSR framework based on Vue3, with static generation via nuxt generate.
• One-command deploy — npm run deploy runs nuxt generate && gh-pages --dotfiles -d .output/public, combining the build and branch push in a single step.
• Configurable baseURL — nuxt.config.ts includes an app.baseURL option; leave it empty for user pages like username.github.io, or set it to /repo-name/ for project pages like this one.
• gh-pages integration — Directly uses the gh-pages library, which creates the gh-pages branch on the first deploy and pushes only the .output/public folder thereafter.
• Dotfile support — The --dotfiles flag ensures hidden files in the build output are included in the published branch.
• Minimal and unopinionated — The template includes no extra UI frameworks, styling system, or pre-built page sections, making it a clean starting point for any Nuxt3 project.
• Free hosting — Deployment targets GitHub Pages, which serves static sites free of charge.

Who is it for?

• Nuxt3 developers — Anyone building with Nuxt3 who wants a working example of deploying to GitHub Pages without writing custom deploy scripts.
• Static site authors — Users who prefer nuxt generate for pre-rendered output and need a simple, no-frills hosting path via GitHub Pages.
• Open-source maintainers — Project maintainers who want to publish a project site or documentation from a repository to the gh-pages branch, supporting both user and project page URLs.

What can you do with it?

• Launch a personal homepage — For a username.github.io repository, set baseURL to an empty string and the site appears at the root of your GitHub Pages domain.
• Create a project site — For a normal repository, set baseURL to the repository name, and the site lives at https://username.github.io/repo-name/.
• Rerun deploys easily — After the initial npm run deploy creates the gh-pages branch, you can repeat the same command to publish site updates.

How does it work?

The workflow starts by editing app.baseURL in nuxt.config.ts to match your target GitHub Pages location. You install dependencies with npm install, verify locally with npm run dev, then run npm run deploy. That command builds the static site into .output/public and uses gh-pages to push that directory to the gh-pages branch. Finally, in the repository Settings > Pages menu, you select the gh-pages branch as the publishing source, and GitHub Pages serves the site.

FAQ

How do I deploy my own Nuxt3 app to GitHub Pages?

Set app.baseURL to the appropriate value (empty for user pages, the repo name with slashes for project pages), run npm install, then run npm run deploy. Once the script pushes to the gh-pages branch, go to Settings > Pages and choose that branch as the source.

What does npm run deploy actually do?

It executes nuxt generate && gh-pages --dotfiles -d .output/public. First it generates a static version of the app into .output/public, then the gh-pages library commits and pushes that folder to the gh-pages branch, preserving dotfiles via the --dotfiles flag.

Do I need to configure baseURL for a project page?

Yes. If your repository is not named username.github.io, you must set app.baseURL to the repository name, such as /nuxt3-ghpages/. Otherwise asset and route paths may break on the hosted site.

Can I host a user page with this template?

Yes. For a user or organization page hosted in a username.github.io repository, you can delete the app.baseURL property or leave it as an empty string, and the site will be served from the root.

Is this template free?

The template is public on GitHub and uses free building blocks: Nuxt3 is open source, the gh-pages npm library is free, and GitHub Pages offers free static hosting. No paid services are required unless you add a custom domain.