Vue Router, GitHub Pages, and Custom Domain Not Working With Routed Links

Question

My domain: myname.com
My GitHub repo: myname
My GitHub name: myname

Underlying GH-Pages URL: myname.github.io/myname

My Issue: I have the following pages set up with a History Vue Router: home, contact, projects.
Whenever I go to myname.com/contact, it routes me to 404 instead. When I click on a link to redirect me to /contacts, it pushes it to the address bar but if you refresh, it routes to 404. I have read posts such as: Deploy Vue to GitHub Pages. Error with vue-router and Vue router on page refresh gets 404 but the issue persists and the custom domain is an added complexity. I have also read this: Vue Router return 404 when revisit to the url but, there is an example of a React Router page with a Browser Router working on GH-Pages: https://milosrancic.github.io/reactjs-website/activities, repo: https://github.com/milosrancic/reactjs-website.

Here is what I have done:

My package.json has the following line: "homepage": "https://myname.com/"
My vue.config.js is exactly this:

module.exports = {
    publicPath: '/'
  }

My Router is on my path: /src/router/index.js, passed into main.js new Vue(), and is exported like this:

export default new VueRouter({
    base: process.env.BASE_URL,
    mode: 'history',
    routes
})

Inside my App.vue (entry component), the template looks like this:

<template>
  <div id="app">
    <nav-bar></nav-bar>
    <router-view></router-view>
  </div>
</template>

GitHub doesn't redirect these requests to your app. router.vuejs.org/guide/essentials/history-mode.html for the explanation. A quick fix would be removing mode: 'history' — wiomoc
The "react" answer you linked applies to your app as well. It doesn't matter what technology.framework your SPA uses. You still need to tell the router to redirect to your app's entry point when a particular route (or all, for that matter) is (are) requested. Without the router pointing the request to the app, the app is oblivious to the request and the router responds with a 404. I'm not sure if github offers the ability of a catchall/redirect in their free package. An alternative is to ditch mode: 'history' because then all your app links will point to the entry url (with different #). — tao
So there is no way to use a History/Browser router with GH-Pages? I would prefer not to have the hash in front of URLs. I don't think I can provide .htaccess files to my repo to have it apply on my page. Perhaps I need to move away from GH-Pages for this? @tao — Alex Diamond
There surely is. But I don't know if GitHub offers it for free. Point here being: your question has nothing to do with Vue and everything to do with GitHub routing settings. Meaning: you might find your answer if you look for any React, Angular, Vue, Svelte or any other alternative for SPA, hosted on GitHub. But it's about how to setup GitHub, not the app. — tao
Ok, so this guy made a pretty cool solution. GH allows you to use your own 404 template. Instead of that template he placed a page which redirects to the entry point with the correct URL. I'm not yet sure how he masks it in the browser address, though. While out of the box, I imagine the solution has a negative effect on SEO. — tao

Alex Diamond Alex Diamond · Accepted Answer · 2020-12-30T05:49:01

I was unable to fix the problem through Vue but, as tao mentioned, this is likely an issue with GitHub and how they handle URLs. The simplest fix is to use a Hash Router instead so that the entry URL stays static. However, this will introduce that, arguably distasteful /#/ in your URL.

Given how catch-all routes are not supported natively, someone has found a workaround for this: https://github.com/rafgraph/spa-github-pages. Note: This is likely not good for SEO because the intended URLs do not actually exist. This is doing a trick with their 404 redirects and handling it on the index page. This was for a portfolio site and as such, I am ok with this for now. If I, or someone else, finds a better solution, this will be updated.

Workaround:

Inside /public add a file called 404.html and paste the following contents:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>CHANGE THIS TO YOUR TITLE</title>
    <script type="text/javascript">
      // MIT License
      // https://github.com/rafgraph/spa-github-pages
      // This script takes the current url and converts the path and query
      // string into just a query string, and then redirects the browser
      // to the new url with only a query string and hash fragment,
      // e.g. https://www.foo.tld/one/two?a=b&c=d#qwe, becomes
      // https://www.foo.tld/?/one/two&a=b~and~c=d#qwe
      // Note: this 404.html file must be at least 512 bytes for it to work
      // with Internet Explorer (it is currently > 512 bytes)

      // If you're creating a Project Pages site and NOT using a custom domain,
      // then set pathSegmentsToKeep to 1 (enterprise users may need to set it to > 1).
      // This way the code will only replace the route part of the path, and not
      // the real directory in which the app resides, for example:
      // https://username.github.io/repo-name/one/two?a=b&c=d#qwe becomes
      // https://username.github.io/repo-name/?/one/two&a=b~and~c=d#qwe
      // Otherwise, leave pathSegmentsToKeep as 0.
      var pathSegmentsToKeep = 0;

      var l = window.location;
      l.replace(
        l.protocol + '//' + l.hostname + (l.port ? ':' + l.port : '') +
        l.pathname.split('/').slice(0, 1 + pathSegmentsToKeep).join('/') + '/?/' +
        l.pathname.slice(1).split('/').slice(pathSegmentsToKeep).join('/').replace(/&/g, '~and~') +
        (l.search ? '&' + l.search.slice(1).replace(/&/g, '~and~') : '') +
        l.hash
      );

    </script>
  </head>
  <body>
  </body>
</html>

Inside /public/index.html, add the following inside the <head> right after <title>:

<script type="text/javascript">
// MIT License
// https://github.com/rafgraph/spa-github-pages
// This script checks to see if a redirect is present in the query string,
// converts it back into the correct url and adds it to the
// browser's history using window.history.replaceState(...),
// which won't cause the browser to attempt to load the new url.
// When the single page app is loaded further down in this file,
// the correct url will be waiting in the browser's history for
// the single page app to route accordingly.
(function(l) {
    if (l.search[1] === '/' ) {
    var decoded = l.search.slice(1).split('&').map(function(s) { 
        return s.replace(/~and~/g, '&')
    }).join('?');
    window.history.replaceState(null, null,
        l.pathname.slice(0, -1) + decoded + l.hash
    );
    }
}(window.location))
</script>

This has worked for me and I can now visit the contacts page by simply entering myname.com/contact. This should also work if you have nested SPA inside /public, using the same trick.

Vue Router, GitHub Pages, and Custom Domain Not Working With Routed Links

2 Answers