How can I configure Vite's dev server to give 404 errors?

Question

Using Vite's dev server, if I try to access a non-existent URL (e.g. localhost:3000/nonexistent/index.html), I would expect to receive a 404 error. Instead I receive a 200 status code, along with the contents of localhost:3000/index.html.

How can I configure Vite so that it returns a 404 in this situation?

(This question: Serve a 404 page with app created with Vue-CLI, is very similar but relates to the Webpack-based Vue-CLI rather than Vite.)

Answer 1

Vite 3

Vite 3.x introduced appType, which can be used to enable/disable the history fallback. Setting it to 'mpa' disables the history fallback while keeping the index.html transform and the 404 handler enabled. The naming is somewhat misleading, as it implies the mode is only for MPAs, but on the contrary, you can use this mode for SPAs:

import { defineConfig } from 'vite'

export default defineConfig({
  appType: 'mpa', // disable history fallback
})

Note the history fallback normally rewrites / to /index.html, so you'd have to insert your own middleware to do that if you want to keep that behavior:

import { defineConfig } from 'vite'

const rewriteSlashToIndexHtml = () => {
  return {
    name: 'rewrite-slash-to-index-html',
    apply: 'serve',
    enforce: 'post',
    configureServer(server) {
      // rewrite / as index.html
      server.middlewares.use('/', (req, _, next) => {
        if (req.url === '/') {
          req.url = '/index.html'
        }
        next()
      })
    },
  }
}

export default defineConfig({
  appType: 'mpa', // disable history fallback
  plugins: [
    rewriteSlashToIndexHtml(),
  ],
})

Vite 2

Vite 2.x does not support disabling the history API fallback out of the box.

As a workaround, you can add a Vite plugin that removes Vite's history API fallback middleware (based on @ChrisCalo's answer):

// vite.config.js
import { defineConfig } from 'vite'

const removeViteSpaFallbackMiddleware = (middlewares) => {
  const { stack } = middlewares
  const index = stack.findIndex(({ handle }) => handle.name === 'viteSpaFallbackMiddleware')
  if (index > -1) {
    stack.splice(index, 1)
  } else {
    throw Error('viteSpaFallbackMiddleware() not found in server middleware')
  }
}

const removeHistoryFallback = () => {
  return {
    name: 'remove-history-fallback',
    apply: 'serve',
    enforce: 'post',
    configureServer(server) {
      // rewrite / as index.html
      server.middlewares.use('/', (req, _, next) => {
        if (req.url === '/') {
          req.url = '/index.html'
        }
        next()
      })

      return () => removeViteSpaFallbackMiddleware(server.middlewares)
    },
  }
}

export default defineConfig({
  plugins: [
    removeHistoryFallback(),
  ],
})

One disadvantage of this plugin is it relies on Vite's own internal naming of the history fallback middleware, which makes this workaround brittle.

Answer 2

Here's an approach that doesn't try to check what's on disk (which yielded incorrect behavior for me).

Instead, this approach:

1. removes Vite's SPA fallback middleware
2. it uses Vite's built-in HTML transformation and returns /dir/index.html (if it exists) for /dir or /dir/ requests
3. 404s for everything else

// express not necessary, but its API does simplify things
const express = require("express");
const { join } = require("path");
const { readFile } = require("fs/promises");

// ADJUST THIS FOR YOUR PROJECT
const PROJECT_ROOT = join(__dirname, "..");

function removeHistoryFallback() {
  return {
    name: "remove-history-fallback",
    configureServer(server) {
      // returned function runs AFTER Vite's middleware is built
      return function () {
        removeViteSpaFallbackMiddleware(server.middlewares);
        server.middlewares.use(transformHtmlMiddleware(server));
        server.middlewares.use(notFoundMiddleware());
      };
    },
  };
}

function removeViteSpaFallbackMiddleware(middlewares) {
  const { stack } = middlewares;
  const index = stack.findIndex(function (layer) {
    const { handle: fn } = layer;
    return fn.name === "viteSpaFallbackMiddleware";
  });
  if (index > -1) {
    stack.splice(index, 1);
  } else {
    throw Error("viteSpaFallbackMiddleware() not found in server middleware");
  }
}

function transformHtmlMiddleware(server) {
  const middleware = express();
  middleware.use(async (req, res, next) => {
    try {
      const rawHtml = await getIndexHtml(req.path);
      const transformedHtml = await server.transformIndexHtml(
        req.url, rawHtml, req.originalUrl
      );
      
      res.set(server.config.server.headers);
      res.send(transformedHtml);
    } catch (error) {
      return next(error);
    }
  });
  
  // named function for easier debugging
  return function customViteHtmlTransformMiddleware(req, res, next) {
    middleware(req, res, next);
  };
}

async function getIndexHtml(path) {
  const indexPath = join(PROJECT_ROOT, path, "index.html");
  return readFile(indexPath, "utf-8");
}

function notFoundMiddleware() {
  const middleware = express();
  middleware.use((req, res) => {
    const { method, path } = req;
    res.status(404);
    res.type("html");
    res.send(`<pre>Cannot ${method} ${path}</pre>`);
  });
  return function customNotFoundMiddleware(req, res, next) {
    middleware(req, res, next);
  };
}

module.exports = {
  removeHistoryFallback,
};

What's funny is that Vite seems to take the stance that:

• it's a dev and build tool only, it's not to be used in production
• built files are meant to be served statically, therefore, it doesn't come with a production server

However, for static file servers:

• some configurations of static file servers will return index files when a directory is requested
• they generally don't fallback to serving index.html when a file is not found and instead return a 404 in those situations

Therefore, it doesn't make much sense that Vite's dev server has this fallback behavior when it's targeting production environments that don't have it. It would be nice if there were a "correct" way to just turn off the history fallback while keeping the rest of the serving behavior (HTML transformation, etc).

Answer 3

You could modify fallback middleware to change the default behaves, or anything else you want. Here is an example. https://github.com/legend-chen/vite-404-redirect-plugin