feat: Add historyApiFallback option

README.md

@@ -173,6 +173,13 @@ The public path that the middleware is bound to.
 
 _Best Practice: use the same `publicPath` defined in your webpack config. For more information about `publicPath`, please see [the webpack documentation](https://webpack.js.org/guides/public-path)._
 
+### historyApiFallback
+
+type: `Boolean`
+Default: `false`
+
+When using the HTML5 History API, the index.html page will likely have to be served in place of any 404 responses. Enable historyApiFallback by setting it to true
+
 ### stats
 
 Type: `Boolean|String|Object`

src/index.js

@@ -45,7 +45,7 @@ const noop = () => {};
  */
 
 /**
- * @typedef {Compiler["outputFileSystem"] & { createReadStream?: import("fs").createReadStream, statSync?: import("fs").statSync, lstat?: import("fs").lstat, readFileSync?: import("fs").readFileSync }} OutputFileSystem
+ * @typedef {Compiler["outputFileSystem"] & { createReadStream?: import("fs").createReadStream, statSync?: import("fs").statSync, lstat?: import("fs").lstat, existsSync?: import("fs").existsSync, readFileSync?: import("fs").readFileSync }} OutputFileSystem
  */
 
 /** @typedef {ReturnType<Compiler["getInfrastructureLogger"]>} Logger */
@@ -88,6 +88,7 @@ const noop = () => {};
  * @property {boolean} [serverSideRender]
  * @property {OutputFileSystem} [outputFileSystem]
  * @property {boolean | string} [index]
+ * @property {boolean | undefined} [historyApiFallback]
  */
 
 /**

src/options.json

@@ -72,6 +72,10 @@
         }
       ]
     },
+    "historyApiFallback": {
+      "description": "When using the HTML5 History API, the index.html page will likely have to be served in place of any 404 responses. Enable historyApiFallback by setting it to true",
+      "type": "boolean"
+    },
     "stats": {
       "description": "Stats options object or preset name.",
       "link": "https://github.com/webpack/webpack-dev-middleware#stats",

src/utils/getFilenameFromUrl.js

@@ -95,8 +95,15 @@ function getFilenameFromUrl(context, url) {
         filename = path.join(outputPath, querystring.unescape(pathname));
       }
 
-      let fsStats;
+      if (
+        options.historyApiFallback &&
+        context.outputFileSystem.existsSync &&
+        !context.outputFileSystem.existsSync(filename)
+      ) {
+        filename = path.join(outputPath);
+      }
 
+      let fsStats;
       try {
         fsStats =
           /** @type {import("fs").statSync} */

test/__snapshots__/validation-options.test.js.snap.webpack5

@@ -39,6 +39,18 @@ exports[`validation should throw an error on the "headers" option with "true" va
     * options.headers should be an instance of function."
 `;
 
+exports[`validation should throw an error on the "historyApiFallback" option with "10" value 1`] = `
+"Invalid options object. Dev Middleware has been initialized using an options object that does not match the API schema.
+ - options.historyApiFallback should be a boolean.
+   -> When using the HTML5 History API, the index.html page will likely have to be served in place of any 404 responses. Enable historyApiFallback by setting it to true"
+`;
+
+exports[`validation should throw an error on the "historyApiFallback" option with "foo" value 1`] = `
+"Invalid options object. Dev Middleware has been initialized using an options object that does not match the API schema.
+ - options.historyApiFallback should be a boolean.
+   -> When using the HTML5 History API, the index.html page will likely have to be served in place of any 404 responses. Enable historyApiFallback by setting it to true"
+`;
+
 exports[`validation should throw an error on the "index" option with "{}" value 1`] = `
 "Invalid options object. Dev Middleware has been initialized using an options object that does not match the API schema.
  - options.index should be one of these:

test/middleware.test.js

@@ -3040,6 +3040,27 @@ describe.each([
       });
     });
 
+    describe("historyApiFallback option", () => {
+      describe("index.html page will likely have to be served in place of any 404 responses", () => {
+        beforeAll((done) => {
+          const compiler = getCompiler(webpackConfig);
+
+          instance = middleware(compiler, { historyApiFallback: true });
+
+          app = framework();
+          app.use(instance);
+
+          listen = listenShorthand(done);
+        });
+
+        afterAll(close);
+
+        it('should return the "200" code for the "GET" request', (done) => {
+          request(app).get("/foo/bar/baz").expect(200, done);
+        });
+      });
+    });
+
     describe("serverSideRender option", () => {
       let locals;
 

test/validation-options.test.js

@@ -39,6 +39,10 @@ describe("validation", () => {
       success: ["/foo", "", "auto", () => "/public/path"],
       failure: [false],
     },
+    historyApiFallback: {
+      success: [true],
+      failure: [],
+    },
     serverSideRender: {
       success: [true],
       failure: ["foo", 0],

types/index.d.ts

@@ -28,7 +28,7 @@ export = wdm;
  * @typedef {ReturnType<Compiler["watch"]>} MultiWatching
  */
 /**
- * @typedef {Compiler["outputFileSystem"] & { createReadStream?: import("fs").createReadStream, statSync?: import("fs").statSync, lstat?: import("fs").lstat, readFileSync?: import("fs").readFileSync }} OutputFileSystem
+ * @typedef {Compiler["outputFileSystem"] & { createReadStream?: import("fs").createReadStream, statSync?: import("fs").statSync, lstat?: import("fs").lstat, existsSync?: import("fs").existsSync, readFileSync?: import("fs").readFileSync }} OutputFileSystem
  */
 /** @typedef {ReturnType<Compiler["getInfrastructureLogger"]>} Logger */
 /**
@@ -66,6 +66,7 @@ export = wdm;
  * @property {boolean} [serverSideRender]
  * @property {OutputFileSystem} [outputFileSystem]
  * @property {boolean | string} [index]
+ * @property {boolean | undefined} [historyApiFallback]
  */
 /**
  * @template {IncomingMessage} RequestInternal
@@ -172,6 +173,7 @@ type Options<
   serverSideRender?: boolean | undefined;
   outputFileSystem?: OutputFileSystem | undefined;
   index?: string | boolean | undefined;
+  historyApiFallback?: boolean | undefined;
 };
 type API<
   RequestInternal extends import("http").IncomingMessage,
@@ -204,6 +206,7 @@ type OutputFileSystem = Compiler["outputFileSystem"] & {
   createReadStream?: typeof import("fs").createReadStream;
   statSync?: import("fs").StatSyncFn;
   lstat?: typeof import("fs").lstat;
+  existsSync?: typeof import("fs").existsSync;
   readFileSync?: typeof import("fs").readFileSync;
 };
 type Logger = ReturnType<Compiler["getInfrastructureLogger"]>;