Troubleshooting 404 or 500 Error After Deploying Vue 3 App to IIS

Deploying a Vue 3 application to Internet Information Services (IIS) can sometimes lead to unexpected issues, such as 404 errors when accessing routes and especially when we refresh the page.

This is because when we build a Vue app using the Vue CLI command, It generates an index.html file and related js and CSS files. It is more likely a static HTML site with only one HTML physical file named index.html.

So when we are on another route in the vue application like /time-table and suddenly refresh the page, IIS looks for a physical HTML file named time-table.html, and when IIS doesn't find it, it through a 404 error because the generated dist folder has only one html file that is index.html.

In this article, we’ll walk through the steps necessary to properly deploy a Vue 3 app on IIS and resolve common 404 or 500 errors.

There are two solutions for the above issue.

1. We can use hash(#) routing mode by creating a vue router with createWebHashHistory mode.
2. We can rewrite the URL by writing the URL rules in the web.config file for IIS.

Solution 1. In the Vue app, There are two route modes.

1. Hash Mode
2. History Mode

We create vue routes by using Hash Mode. When we create routes using this mode, then it will not change the app's actual path(/home). Instead, it uses the hash portion of the URL (the part after #) to keep track of the current route.

For example, if we are using History Mode, then the path will be like http://example.com/home.

And if we are using Hash Mode, then the path will be like http://example.com/#/home

Solution 2. Since Vue Router often utilizes HTML5 History mode by default, you'll need to set up URL rewriting to ensure that all routes redirect to index.html. To do so, you need to add a web.config file to the dist folder and write URL rules. However, these URL rewrite rules will work only if you have installed the URL rewrite module for IIS.

Steps

1. Download the URL Rewrite Module (https://www.iis.net/downloads/microsoft/url-rewrite) from the official Microsoft website.
2. Install the module and restart IIS.

Now, add the web.config file to the dist folder and add the below config setting to the web.config file.

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Vue Routes" stopProcessing="true">
          <match url=".*" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="/" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

Explanation of the new rules.

• match url=".*": Matches all incoming requests.
• conditions: Checks if the requested file or directory does not exist.
• action: Rewrite the URL to serve the index.html file for any unmatched routes.

After deployment, access your application using the appropriate URL. Test various routes to ensure everything is working correctly.

Conclusion

Deploying a Vue 3 application on IIS can be straightforward with the right configurations. By following the steps outlined above and implementing URL rewriting, you can effectively handle client-side routing and eliminate common 404 errors.

Feel free to reach out with any questions or share your experiences deploying Vue applications!