How to deploy Vue app to GitHub Pages
Łukasz Holeczek
Follow Łukasz Holeczek on GitHub
Connect with Łukasz Holeczek on LinkedIn
Follow Łukasz Holeczek on X (Twitter)
GitHub Pages provides free static site hosting directly from your GitHub repository, perfect for Vue applications with automatic deployments via GitHub Actions. As the creator of CoreUI with 12 years of Vue.js development experience, I’ve deployed hundreds of Vue applications to GitHub Pages, providing fast, reliable hosting for documentation sites, portfolios, and demo applications.
The fastest approach uses GitHub Actions for automatic deployment on every push to main branch.
Configure Vue for GitHub Pages
Update vite.config.js:
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
base: '/your-repo-name/', // Important for GitHub Pages
build: {
outDir: 'dist'
}
})
For root domain (username.github.io):
export default defineConfig({
plugins: [vue()],
base: '/' // Use root path
})
Manual Deployment
# Build production bundle
npm run build
# Navigate to build output
cd dist
# Initialize git
git init
git add -A
git commit -m 'Deploy'
# Push to gh-pages branch
git push -f [email protected]:username/repo.git main:gh-pages
cd ..
Deployment Script
Create deploy.sh:
#!/usr/bin/env sh
# Abort on errors
set -e
# Build
npm run build
# Navigate to build output
cd dist
# Create .nojekyll to bypass Jekyll processing
touch .nojekyll
# If deploying to custom domain
# echo 'www.example.com' > CNAME
git init
git add -A
git commit -m 'Deploy'
# Deploy to gh-pages branch
git push -f [email protected]:username/repo.git main:gh-pages
cd ..
Make executable and run:
chmod +x deploy.sh
./deploy.sh
GitHub Actions Deployment
Create .github/workflows/deploy.yml:
name: Deploy to GitHub Pages
on:
push:
branches:
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build
run: npm run build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./dist
cname: www.example.com # Optional: for custom domain
Configure Repository Settings
- Go to repository Settings → Pages
- Set Source to “Deploy from a branch”
- Select branch:
gh-pages - Select folder:
/ (root) - Click Save
Router Configuration for GitHub Pages
Update router for hash mode:
// src/router/index.js
import { createRouter, createWebHashHistory } from 'vue-router'
import Home from '../views/Home.vue'
const routes = [
{
path: '/',
name: 'Home',
component: Home
},
{
path: '/about',
name: 'About',
component: () => import('../views/About.vue')
}
]
const router = createRouter({
history: createWebHashHistory(), // Use hash mode for GitHub Pages
routes
})
export default router
Or use history mode with 404 fallback:
import { createRouter, createWebHistory } from 'vue-router'
const router = createRouter({
history: createWebHistory('/your-repo-name/'),
routes
})
Create public/404.html:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Redirecting...</title>
<script>
// Redirect to index.html with path as query
const path = window.location.pathname.slice(1)
if (path) {
window.location.replace(
window.location.origin + '/?redirect=' + path
)
}
</script>
</head>
<body></body>
</html>
Custom Domain Setup
Create public/CNAME:
www.example.com
Configure DNS:
Type Name Value
A @ 185.199.108.153
A @ 185.199.109.153
A @ 185.199.110.153
A @ 185.199.111.153
CNAME www username.github.io
Environment Variables
Create .env.production:
VITE_API_URL=https://api.example.com
VITE_APP_TITLE=My Vue App
Access in Vue:
<script setup>
const apiUrl = import.meta.env.VITE_API_URL
const appTitle = import.meta.env.VITE_APP_TITLE
console.log('API URL:', apiUrl)
</script>
Optimize for GitHub Pages
Update vite.config.js:
export default defineConfig({
plugins: [vue()],
base: '/your-repo-name/',
build: {
outDir: 'dist',
assetsDir: 'assets',
rollupOptions: {
output: {
manualChunks: {
vendor: ['vue', 'vue-router']
}
}
}
}
})
Preview Deployment Locally
# Build
npm run build
# Serve with correct base path
npx serve -s dist -l 3000
# Or use vite preview
npm run build
npm run preview
Best Practice Note
This is how we deploy CoreUI Vue templates to GitHub Pages for free, fast hosting. GitHub Pages combined with GitHub Actions provides automatic deployment on every push, making it perfect for documentation sites, portfolios, and demo applications. Always configure the correct base path in vite.config.js, use hash mode for router or implement 404 fallback for history mode, and add .nojekyll file to prevent Jekyll processing.
For production applications, consider using CoreUI’s Vue Admin Template which includes deployment configurations for GitHub Pages.
Related Articles
For other deployment options, check out how to deploy Vue app to Vercel and how to deploy Vue app to Netlify.
