Different History modes

Watch a free video lesson on Vue School

The history option when creating the router instance allows us to choose among different history modes.

Hash Mode

The hash history mode is created with createWebHashHistory():

  1. import { createRouter, createWebHashHistory } from 'vue-router'
  3. const router = createRouter({
  4.   history: createWebHashHistory(),
  5.   routes: [
  6.     //...
  7.   ],
  8. })

It uses a hash character (#) before the actual URL that is internally passed. Because this section of the URL is never sent to the server, it doesn’t require any special treatment on the server level. It does however have a bad impact in SEO. If that’s a concern for you, use the HTML5 history mode.

HTML5 Mode

The HTML5 mode is created with createWebHistory() and is the recommended mode:

  1. import { createRouter, createWebHistory } from 'vue-router'
  3. const router = createRouter({
  4.   history: createWebHistory(),
  5.   routes: [
  6.     //...
  7.   ],
  8. })

When using history mode, the URL will look “normal,” e.g. https://example.com/user/id. Beautiful!

Here comes a problem, though: Since our app is a single page client side app, without a proper server configuration, the users will get a 404 error if they access https://example.com/user/id directly in their browser. Now that’s ugly.

Not to worry: To fix the issue, all you need to do is add a simple catch-all fallback route to your server. If the URL doesn’t match any static assets, it should serve the same index.html page that your app lives in. Beautiful, again!

Example Server Configurations

Note: The following examples assume you are serving your app from the root folder. If you deploy to a subfolder, you should use the publicPath option of Vue CLI and the related base property of the router. You also need to adjust the examples below to use the subfolder instead of the root folder (e.g. replacing RewriteBase / with RewriteBase /name-of-your-subfolder/).

Apache

  1. <IfModule mod_rewrite.c>
  2.   RewriteEngine On
  3.   RewriteBase /
  4.   RewriteRule ^index\.html$ - [L]
  5.   RewriteCond %{REQUEST_FILENAME} !-f
  6.   RewriteCond %{REQUEST_FILENAME} !-d
  7.   RewriteRule . /index.html [L]
  8. </IfModule>

Instead of mod_rewrite, you could also use FallbackResource.

nginx

  1. location / {
  2.   try_files $uri $uri/ /index.html;
  3. }

Native Node.js

  1. const http = require('http')
  2. const fs = require('fs')
  3. const httpPort = 80
  5. http
  6.   .createServer((req, res) => {
  7.     fs.readFile('index.html', 'utf-8', (err, content) => {
  8.       if (err) {
  9.         console.log('We cannot open "index.html" file.')
  10.       }
  12.       res.writeHead(200, {
  13.         'Content-Type': 'text/html; charset=utf-8',
  14.       })
  16.       res.end(content)
  17.     })
  18.   })
  19.   .listen(httpPort, () => {
  20.     console.log('Server listening on: http://localhost:%s', httpPort)
  21.   })

Express with Node.js

For Node.js/Express, consider using connect-history-api-fallback middleware.

Internet Information Services (IIS)

  1. Install IIS UrlRewrite
  2. Create a web.config file in the root directory of your site with the following:
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <configuration>
  3.   <system.webServer>
  4.     <rewrite>
  5.       <rules>
  6.         <rule name="Handle History Mode and custom 404/500" stopProcessing="true">
  7.           <match url="(.*)" />
  8.           <conditions logicalGrouping="MatchAll">
  9.             <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
  10.             <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
  11.           </conditions>
  12.           <action type="Rewrite" url="/" />
  13.         </rule>
  14.       </rules>
  15.     </rewrite>
  16.   </system.webServer>
  17. </configuration>

Caddy v2

  1. try_files {path} /

Caddy v1

  1. rewrite {
  2.     regexp .*
  3.     to {path} /
  4. }

Firebase hosting

Add this to your firebase.json:

  1. {
  2.   "hosting": {
  3.     "public": "dist",
  4.     "rewrites": [
  5.       {
  6.         "source": "**",
  7.         "destination": "/index.html"
  8.       }
  9.     ]
  10.   }
  11. }

Netlify

Create a _redirects file that is included with your deployed files:

  1. /* /index.html 200

In vue-cli, nuxt, and vite projects, this file usually goes under a folder named static or public.

You can more about the syntax on Netlify documentation. You can also create a netlify.toml to combine redirections with other Netlify features.

Caveat

There is a caveat to this: Your server will no longer report 404 errors as all not-found paths now serve up your index.html file. To get around the issue, you should implement a catch-all route within your Vue app to show a 404 page:

  1. const router = createRouter({
  2.   history: createWebHistory(),
  3.   routes: [{ path: '/:pathMatch(.*)', component: NotFoundComponent }],
  4. })

Alternatively, if you are using a Node.js server, you can implement the fallback by using the router on the server side to match the incoming URL and respond with 404 if no route is matched. Check out the Vue server side rendering documentation for more information.