DEV Community

Cover image for Publish your Quasar SPA on with History Mode
Jeff Galbraith for Quasar

Posted on

Publish your Quasar SPA on with History Mode

Frustrated with, because you can't run your Quasar SPA in history mode? Well, now you can!


This article is intended to help you get your SPA published on with history mode turned on. This isn't a straight up process, so I figured I'd write some instructions on how to do it, to help out others who might be running into problems with this process.


Vue-Router has two modes; 1) hash and 2) history.

With hash mode, there is only a single web page and routing takes over to display your pages correctly. Any backend server will be set up to serve only the index file.

With history mode, the concept is similar. However, the server is expecting static pages and for it to be handling the routing. If you have control over your own server, you would write some rewrite rules so the index file will be loaded, and just the index file, for every page, so the vue-router can take over from there.

So, you might also be asking yourself...

If hash mode works fine on, why would anyone want to use history mode?

For myself, I wanted to be able to use anchor links. So, given a url with a hash symbol in it, the proper page will load up and content will automatically scroll to the anchor link.

The Conumdrum with

At the time I was investigating this, didn't allow you to write any sort of server rewrite rules. The information I found was sparse. Maybe it can be done, as I did this a while ago and things change. I can only tell you what worked for me then and still works for me now.


Inside your quasar.conf.js you can set up the publicPath. What this does is put the public path data from the publicPath variable in front of all your resource calls.

    build: {
      vueRouterMode: 'history',
      publicPath: 'app-extension-qmarkdown',
Enter fullscreen mode Exit fullscreen mode

Notice the publicPath? This is for my component, QMarkdown, which lives at And, the url would be this:

Using this publicPath allows me to develop locally and then, when I build the site, the publicPath is injected so resources can properly be found by the browser.

The 404 on

If you drop a 404.html into root of your SPA app, when a page is not found, it will be called. Since vue-router will be managing the routing, this 404.html page will be called for any presumably static page that doesn't exist (meaning, all your routes!).

I came up with a way to leverage this 404.html file. It took a while (over a week) to figure this all out and finalize it.

Basically, this is what your 404.html should look like:

<!DOCTYPE html>
<html lang="en">

  <meta charset="utf-8" />

  <title>404 Redirect</title>

    sessionStorage.redirect = location.href;

  <meta http-equiv="refresh" content="0;URL='/app-extension-qmarkdown'"></meta>


Enter fullscreen mode Exit fullscreen mode

Notice the meta tag with URL. This needs to match your publicPath route in order for it to work.

You may also be wondering why there are all the spaces between the body tags. There was some issue with Internet Explorer. If the file was too small, it just wouldn't read it.

The Last Trick

The 404.html is running a snippet of JavaScript to put the current route into sessionStorage. This is key to getting this all to work. We have to use this sessionStorage to get back on track with vue-router.

In your index.template.html file, you can add the following between the body tags:

          let redirect = sessionStorage.redirect;
          delete sessionStorage.redirect;
          if (redirect && redirect !== location.href) {
            history.replaceState(null, null, redirect);
    <!-- DO NOT touch the following DIV -->
    <div id="q-app"></div>

Enter fullscreen mode Exit fullscreen mode

As you can see, sessionStorage is read, deleted and then history is put back in place. Now, vue-router can take over without issues occurring in the browser.

Final Words

The above happens so fast, you would never know what's happening behind the scenes.

It is my hope that this helps others leverage in history mode, just as it has helped me.

Are you using for publishing your SPA? Let's us also know your experiences or give us feedback about this article. We'd love to hear from you.

Interested in Quasar? Here are some more tips and information:
More info:
Getting Started:
Chat Server:

Top comments (3)

bombxdev profile image
bombxdev • Edited

Hi team, may I know how to set the spa as history mode? I get the 404-page-not-found when try to access http://localhost:9000/second-page.

99hats profile image

Nice article. I'm looking at trying similar on Netlify.

So the publicPath variable is only necessary because you are hosting the site starting from a subpath instead of at the root?

hawkeye64 profile image
Jeff Galbraith

Yes, it's because the path is more that the root path.