How to Properly Host a Vue.js App in a Subdirectory of public_html

Introduction

If you’ve ever tried to deploy a Vue.js application inside a subdirectory of your public_html folder, you might have run into frustrating issues—blank pages, missing assets, or routing failures. I’ve been there. Despite following different guides and tweaking configurations, the app just wouldn’t load properly.

But after a lot of trial and error, I finally got everything working. If you’re struggling with the same issue, this guide will walk you through the exact steps to successfully deploy your Vue.js app in a subdirectory.

I also came across a similar problem similar problem where the issue couldn’t be resolved. Instead, resolved to use a subdomain. However, if you prefer using a subdirectory, follow along.

The Problem

By default, Vue assumes your app will be hosted at the root of a domain (e.g., https://yourdomain.com/). But when you deploy it inside a subdirectory like https://yourdomain.com/Subdirectory/, it may break because the paths to assets and routes aren’t properly set up.

You might see errors like:

1. A blank screen when you visit the subdirectory
2. Missing assets (CSS and JavaScript files not loading)
3. Vue Router not working properly

Let’s go step by step to fix these issues.

Step 1: Set the Correct Base Path in Configuration Files

Depending on whether you are using Vite or Vue CLI, you need to configure either vite.config.js or vue.config.js.

For Vite (vite.config.js)

Edit the vite.config.js file in the root of your Vue project and specify the correct base option:

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import path from 'path';

export default defineConfig({
  plugins: [vue()],
  base: '/subdirectory/', // Change 'subdirectory' to match your subdirectory name
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
});

For Vue CLI (vue.config.js)

If you're using Vue CLI instead of Vite, create or edit vue.config.js:

module.exports = {
  publicPath: '/subdirectory/', // Change 'subdirectory' to match your subdirectory name
};

This ensures that all asset URLs are generated relative to the yoursubdirectory subdirectory.

Step 2: Configure Vue Router (If Used)

If your project uses Vue Router, update the base option to match your subdirectory:

// src/router/index.js
import { createRouter, createWebHistory } from 'vue-router';
import Home from '../views/Home.vue';

const router = createRouter({
  history: createWebHistory('/subdirectory/'), // Ensure this matches your subdirectory
  routes: [
    { path: '/', component: Home },
    // other routes
  ],
});

export default router;

This makes sure the router knows that your app is not running at /, but at /subdirectory/.

Step 3: Set Up .htaccess for Proper Routing

If you’re using Apache, you need to configure an .htaccess file inside the yoursubdirectory folder to handle Vue’s history mode properly. Create a file named .htaccess and add this:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /subdirectory/
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /subdirectory/index.html [L]
</IfModule>

This ensures that all requests go to index.html, allowing Vue Router to handle navigation.

Step 4: Build and Deploy Your App

Now that everything is configured, build your Vue app:

For Vite:

vite build

For Vue CLI:

npm run build

This will generate a dist folder with your production-ready files. Upload the contents of the dist folder to public_html/subdirectory/ using FTP or your hosting’s file manager.

Important: Don’t upload the dist folder itself—upload the files inside it.

Step 5: Clear Cache and Test

After deployment, clear your browser cache or open the site in an incognito window to make sure everything loads properly. If you still see issues, check the browser console (F12 > Console) and the Network tab to see if any assets are failing to load.

Conclusion

Hosting a Vue.js app in a subdirectory of public_html requires proper configuration of the base path, Vue Router, and server settings. By following these steps, your app should now load properly under https://yourdomain.com/subdirectory/.

If you run into issues, double-check your vite.config.js or vue.config.js, router settings, and .htaccess file. Happy coding!