Free Hosting for Your Nuxt App

How to Host Your Nuxt Project on GitHub Pages

Nuxt has quickly become one of the most popular frameworks for building modern web applications with Vue. While it offers powerful features like server-side rendering (SSR), many projects are perfectly fine being deployed as static sites. For personal projects, portfolios, or small apps, GitHub Pages is a free and simple hosting solution.

In this article, I’ll walk you through the complete process of deploying a Nuxt project to GitHub Pages.

---

Why GitHub Pages?

• Free hosting for public repositories.
• Easy integration with GitHub Actions for continuous deployment.
• Great for personal sites, documentation, and small apps.

Since GitHub Pages can only serve static files (HTML, CSS, JavaScript), we need to use Static Site Generation (SSG) in Nuxt.

---

Step 1: Configure nuxt.config.ts

Inside your nuxt.config.ts, make sure you disable SSR and set the correct baseURL.

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: false, // disable server-side rendering
  app: {
    baseURL: '/<your-repo-name>/' // 👈 replace with your repository name
  },
  nitro: {
    preset: 'github-pages'
  }
})

For example, if your repository is named nuxt-portfolio, then your site will be hosted at:

https://<username>.github.io/nuxt-portfolio/

So set baseURL: '/nuxt-portfolio/'.

---

Step 2: Generate Static Files

Run the following command:

yarn generate

This will build your Nuxt project into a dist/ folder, containing static HTML, CSS, and JavaScript files.

---

Step 3: Add a GitHub Actions Workflow

To automate deployment, create a workflow file at .github/workflows/deploy.yml.

Here’s a complete example (for Yarn 4+ projects):

name: Deploy Nuxt to GitHub Pages

on:
  push:
    branches:
      - master   # or main, depending on your repo

permissions:
  contents: write   # allow pushing to gh-pages branch

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 22

      - name: Enable Corepack
        run: corepack enable

      - name: Use Yarn version from packageManager
        run: corepack use yarn

      - name: Install dependencies
        run: yarn install --immutable

      - name: Generate static site
        run: yarn generate

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

This workflow will:

1. Run on every push to master (or main).
2. Install Node.js and Yarn.
3. Build the project with yarn generate.
4. Deploy the dist/ folder to the gh-pages branch.

---

Step 4: Enable GitHub Pages

After the first successful deployment:

1. Go to your repo on GitHub → Settings → Pages.
2. Under Source, select gh-pages branch and folder / (root).
3. Save.

Your site will be live in a few minutes at:

https://<username>.github.io/<repo-name>/

---

Common Pitfalls

• Blank page or missing assets → Check baseURL in nuxt.config.ts.
• Permission denied (403) error → Ensure permissions: contents: write is set in the workflow.
• Wrong Yarn version → Enable Corepack so GitHub Actions installs the correct Yarn version.

---

Conclusion

Hosting your Nuxt project on GitHub Pages is a cost-effective and straightforward solution for static sites. With GitHub Actions, every push to your repo can automatically rebuild and redeploy your site.

This setup is perfect for personal portfolios, documentation, or lightweight apps. If your app eventually needs server-side rendering or API integrations, you can later migrate to platforms like Vercel or Netlify.

---

✨ That’s it! You’ve now got your Nuxt app running on GitHub Pages for free.