Greetings

Hi there!

I was trying some new stuff about VUE recently.

I downloaded a free version of VUE Argon dashboard code and tried to compile it locally.

It’s straghtforward:

nvm use lts/iron
npm install
npm run build

Then I got the dist folder:

Interesting…

Then I double clicked the index.html, expecting it will display the beautiful landing page, but it didn’t happen…

This is strange… What went wrong?

I tried npm run serve, it works well, I can see the portal and navigate between pages without issues.

I must fix this! Should be quick!

Bingo!

The root cause is that the VUE project used router with createWebHistory instead of createWebHashHistory!

It resulted a differenve ways to handle static assets and routing.

1. Absolute Paths for Static Assets: By default, Vue CLI configures the build to use absolute paths for assets (JS, CSS, images, etc.). When I open the index.html file directly in a browser (using the file:// protocol), these paths may not resolve correctly, because they expect to be served from a web server’s root.
2. Single Page Application (SPA) Routing: Vue applications, especially those built with Vue Router in history mode, rely on the web server to correctly handle URLs. Directly opening index.html doesn’t allow Vue Router to intercept and handle the routing, leading to routes possibly not resolving as intended. npm run serve starts a development server that correctly handles SPA routing, serving index.html for all routes.

Using createWebHistory in Production environment is required as it provides several significant benefits:

• Clean URLs: If having clean, professional-looking URLs is important for your application’s user experience or branding, createWebHistory is the preferred choice. This is often the case for public-facing production websites.
• SEO Considerations: For SEO purposes, clean URLs (without hashes) are generally better. However, modern SEO practices and improved search engine capabilities have mitigated these concerns significantly.
• Ease of Deployment: createWebHashHistory is simpler to deploy because it doesn’t require specific server configurations to handle SPA routing. If your hosting environment or knowledge of server configurations is limited, this might be a more straightforward option.
• Refresh Behavior: With createWebHistory, directly refreshing or entering URLs can lead to 404 errors if the server isn’t correctly configured to redirect all such requests to index.html. With createWebHashHistory, this issue doesn’t arise, making it a more foolproof solution for environments where server control is limited.

I just want to use createWebHashHistory in my local development environment.

The fix

Now, the fix is easy.

First, modify scripts in package.json to specify mode for serve and build, and I added two new items serve_prod and build_dev:

"scripts": {
    "serve": "vue-cli-service serve --mode development",
    "serve_prod": "vue-cli-service serve --mode production",
    "build": "vue-cli-service build --mode production",
    "build_dev": "vue-cli-service build --mode development"
  },

Second, creating or editing vue.config.js as below:

module.exports = {
  publicPath: process.env.NODE_ENV === 'production'
    ? '/'
    : '',
}

Lastly, update src/router/index.js to handle the mode accordingly:

The original code was:

import { createRouter, createWebHistory } from "vue-router";

# other existing code

const router = createRouter({
  history: createWebHistory(),
  history: history,
  routes,
  linkActiveClass: "active"
});

Now it looks like this:

import { createRouter, createWebHistory } from "vue-router";

# other existing code

// Determine the history mode based on the environment
const history = process.env.NODE_ENV === 'production'
  ? createWebHistory()
  : createWebHashHistory();

const router = createRouter({
  history: history,
  routes,
  linkActiveClass: "active"
});

Now, run npm run build_dev again, I can see the portal 😎

Thanks for reading!
Have a good day!