@rspack/dev-middleware 2.0.0-beta.2 → 2.0.1

package/README.md

@@ -39,9 +39,9 @@ bun add -D @rspack/dev-middleware
 ## Usage
 
 ```js
-const { devMiddleware } = require("@rspack/dev-middleware");
-const express = require("express");
-const { rspack } = require("@rspack/core");
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import express from "express";
 
 const compiler = rspack({
   // Rspack options
@@ -72,7 +72,7 @@ See [below](#other-servers) for examples of use with other servers.
 |               **[`etag`](#tag)**                |   `boolean\| "weak"\| "strong"`   |                  `undefined`                  | Enable or disable etag generation.                                                                                   |
 |       **[`lastModified`](#lastmodified)**       |             `boolean`             |                  `undefined`                  | Enable or disable `Last-Modified` header. Uses the file system's last modified value.                                |
 |       **[`cacheControl`](#cachecontrol)**       | `boolean\|number\|string\|Object` |                  `undefined`                  | Enable or disable setting `Cache-Control` response header.                                                           |
-|     **[`cacheImmutable`](#cacheimmutable)**     |            `boolean\`             |                  `undefined`                  | Enable or disable setting `Cache-Control: public, max-age=31536000, immutable` response header for immutable assets. |
+|     **[`cacheImmutable`](#cacheimmutable)**     |             `boolean`             |                    `false`                    | Enable or disable setting `Cache-Control: public, max-age=31536000, immutable` response header for immutable assets. |
 |         **[`publicPath`](#publicpath)**         |             `string`              |                  `undefined`                  | The public path that the middleware is bound to.                                                                     |
 |              **[`stats`](#stats)**              |     `boolean\|string\|Object`     |        `stats` (from a configuration)         | Stats options object or preset name.                                                                                 |
 |   **[`serverSideRender`](#serversiderender)**   |             `boolean`             |                  `undefined`                  | Instructs the module to enable or disable the server-side rendering mode.                                            |
@@ -196,21 +196,28 @@ Default: `undefined`
 
 Depending on the setting, the following headers will be generated:
 
-- `Boolean` - `Cache-Control: public, max-age=31536000000`
-- `Number` - `Cache-Control: public, max-age=YOUR_NUMBER`
+- `Boolean` - `Cache-Control: public, max-age=31536000`
+- `Number` - `Cache-Control: public, max-age=YOUR_NUMBER_IN_SECONDS`
 - `String` - `Cache-Control: YOUR_STRING`
-- `{ maxAge?: number, immutable?: boolean }` - `Cache-Control: public, max-age=YOUR_MAX_AGE_or_31536000000`, also `, immutable` can be added if you set the `immutable` option to `true`
+- `{ maxAge?: number, immutable?: boolean }` - `Cache-Control: public, max-age=YOUR_MAX_AGE_IN_SECONDS_or_31536000`, also `, immutable` is added when you set the `immutable` option to `true`
+
+Numeric `cacheControl` and `cacheControl.maxAge` values are interpreted as milliseconds, clamped to `0..31536000000`, and converted to seconds for the response header.
 
 Enable or disable setting `Cache-Control` response header.
 
 ### cacheImmutable
 
 Type: `Boolean`
-Default: `undefined`
+Default: `false`
 
 Enable or disable setting `Cache-Control: public, max-age=31536000, immutable` response header for immutable assets (i.e. asset with a hash like `image.a4c12bde.jpg`).
+
 Immutable assets are assets that have their hash in the file name therefore they can be cached, because if you change their contents the file name will be changed.
-Take preference over the `cacheControl` option if the asset was defined as immutable.
+
+When omitted, immutable assets fall back to the `cacheControl` option.
+
+Set `cacheImmutable: true` to opt into the immutable cache header for hashed assets.
+This takes precedence over the `cacheControl` option only when the asset was defined as immutable and `cacheImmutable` is `true`.
 
 ### publicPath
 
@@ -249,7 +256,7 @@ This option also accepts a `Function` value, which can be used to filter which f
 The function follows the same premise as [`Array#filter`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) in which a return value of `false` _will not_ write the file, and a return value of `true` _will_ write the file to disk. eg.
 
 ```js
-const { rspack } = require("@rspack/core");
+import { rspack } from "@rspack/core";
 
 const configuration = {
   /* Rspack configuration */
@@ -269,16 +276,16 @@ Default: [memfs](https://github.com/streamich/memfs)
 Set the default file system which will be used by Rspack as primary destination of generated files.
 This option isn't affected by the [writeToDisk](#writeToDisk) option.
 
-This can be done simply by using `path.join`:
+This can be done simply by using `node:path`'s `join`:
 
 ```js
-const path = require("node:path");
-const mkdirp = require("mkdirp");
-const myOutputFileSystem = require("my-fs");
-const { rspack } = require("@rspack/core");
+import { join } from "node:path";
+import { rspack } from "@rspack/core";
+import mkdirp from "mkdirp";
+import myOutputFileSystem from "my-fs";
 
-myOutputFileSystem.join = path.join.bind(path); // no need to bind
-myOutputFileSystem.mkdirp = mkdirp.bind(mkdirp); // no need to bind
+myOutputFileSystem.join = join;
+myOutputFileSystem.mkdirp = mkdirp;
 
 const compiler = rspack({
   /* Rspack configuration */
@@ -292,7 +299,7 @@ devMiddleware(compiler, { outputFileSystem: myOutputFileSystem });
 Allows to set up a callback to change the response data.
 
 ```js
-const { rspack } = require("@rspack/core");
+import { rspack } from "@rspack/core";
 
 const configuration = {
   /* Rspack configuration */
@@ -328,9 +335,9 @@ Required: `No`
 A function executed once the middleware has stopped watching.
 
 ```js
-const { devMiddleware } = require("@rspack/dev-middleware");
-const express = require("express");
-const { rspack } = require("@rspack/core");
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import express from "express";
 
 const compiler = rspack({
   /* Rspack configuration */
@@ -338,8 +345,7 @@ const compiler = rspack({
 
 const instance = devMiddleware(compiler);
 
-// eslint-disable-next-line new-cap
-const app = new express();
+const app = express();
 
 app.use(instance);
 
@@ -363,9 +369,9 @@ Required: `No`
 A function executed once the middleware has invalidated.
 
 ```js
-const { devMiddleware } = require("@rspack/dev-middleware");
-const express = require("express");
-const { rspack } = require("@rspack/core");
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import express from "express";
 
 const compiler = rspack({
   /* Rspack configuration */
@@ -373,8 +379,7 @@ const compiler = rspack({
 
 const instance = devMiddleware(compiler);
 
-// eslint-disable-next-line new-cap
-const app = new express();
+const app = express();
 
 app.use(instance);
 
@@ -403,9 +408,9 @@ A function executed when the bundle becomes valid.
 If the bundle is valid at the time of calling, the callback is executed immediately.
 
 ```js
-const { devMiddleware } = require("@rspack/dev-middleware");
-const express = require("express");
-const { rspack } = require("@rspack/core");
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import express from "express";
 
 const compiler = rspack({
   /* Rspack configuration */
@@ -413,8 +418,7 @@ const compiler = rspack({
 
 const instance = devMiddleware(compiler);
 
-// eslint-disable-next-line new-cap
-const app = new express();
+const app = express();
 
 app.use(instance);
 
@@ -437,9 +441,9 @@ Required: `Yes`
 URL for the requested file.
 
 ```js
-const { devMiddleware } = require("@rspack/dev-middleware");
-const express = require("express");
-const { rspack } = require("@rspack/core");
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import express from "express";
 
 const compiler = rspack({
   /* Rspack configuration */
@@ -447,15 +451,26 @@ const compiler = rspack({
 
 const instance = devMiddleware(compiler);
 
-// eslint-disable-next-line new-cap
-const app = new express();
+const app = express();
 
 app.use(instance);
 
 instance.waitUntilValid(() => {
-  const filename = instance.getFilenameFromUrl("/bundle.js");
+  let resolved;
+
+  try {
+    resolved = instance.getFilenameFromUrl("/bundle.js");
+  } catch (error) {
+    console.error(error);
+    return;
+  }
 
-  console.log(`Filename is ${filename}`);
+  if (!resolved) {
+    console.log("Not found");
+    return;
+  }
+
+  console.log(`Filename is ${resolved.filename}`);
 });
 ```
 
@@ -468,9 +483,9 @@ Since `output.publicPath` and `output.filename`/`output.chunkFilename` can be dy
 But there is a solution to avoid it - mount the middleware to a non-root route, for example:
 
 ```js
-const { devMiddleware } = require("@rspack/dev-middleware");
-const express = require("express");
-const { rspack } = require("@rspack/core");
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import express from "express";
 
 const compiler = rspack({
   // Rspack options
@@ -509,17 +524,17 @@ process is finished with server-side rendering enabled._
 Example Implementation:
 
 ```js
-const { devMiddleware } = require("@rspack/dev-middleware");
-const express = require("express");
-const isObject = require("is-object");
-const { rspack } = require("@rspack/core");
+import { join } from "node:path";
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import express from "express";
+import isObject from "is-object";
 
 const compiler = rspack({
   /* Rspack configuration */
 });
 
-// eslint-disable-next-line new-cap
-const app = new express();
+const app = express();
 
 // This function makes server rendering of asset references consistent with different Rspack chunk/entry configurations
 function normalizeAssets(assets) {
@@ -547,16 +562,16 @@ app.use((req, res) => {
     <title>My App</title>
     <style>
     ${normalizeAssets(assetsByChunkName.main)
-      .filter((path) => path.endsWith(".css"))
-      .map((path) => outputFileSystem.readFileSync(path.join(outputPath, path)))
+      .filter((asset) => asset.endsWith(".css"))
+      .map((asset) => outputFileSystem.readFileSync(join(outputPath, asset)))
       .join("\n")}
     </style>
   </head>
   <body>
     <div id="root"></div>
     ${normalizeAssets(assetsByChunkName.main)
-      .filter((path) => path.endsWith(".js"))
-      .map((path) => `<script src="${path}"></script>`)
+      .filter((asset) => asset.endsWith(".js"))
+      .map((asset) => `<script src="${asset}"></script>`)
       .join("\n")}
   </body>
 </html>
@@ -568,14 +583,16 @@ app.use((req, res) => {
 
 Examples of use with other servers will follow here.
 
-### Connect
+### connect-next
+
+[connect-next](https://github.com/rstackjs/connect-next) is an actively maintained fork of Connect.
 
 ```js
-const http = require("node:http");
-const { devMiddleware } = require("@rspack/dev-middleware");
-const connect = require("connect");
-const { rspack } = require("@rspack/core");
-const rspackConfig = require("./rspack.config.js");
+import { createServer } from "node:http";
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import { connect } from "connect-next";
+import rspackConfig from "./rspack.config.js";
 
 const compiler = rspack(rspackConfig);
 const devMiddlewareOptions = {
@@ -585,18 +602,18 @@ const app = connect();
 
 app.use(devMiddleware(compiler, devMiddlewareOptions));
 
-http.createServer(app).listen(3000);
+createServer(app).listen(3000);
 ```
 
 ### Router
 
 ```js
-const http = require("node:http");
-const { devMiddleware } = require("@rspack/dev-middleware");
-const finalhandler = require("finalhandler");
-const Router = require("router");
-const { rspack } = require("@rspack/core");
-const rspackConfig = require("./rspack.config.js");
+import { createServer } from "node:http";
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import finalhandler from "finalhandler";
+import Router from "router";
+import rspackConfig from "./rspack.config.js";
 
 const compiler = rspack(rspackConfig);
 const devMiddlewareOptions = {
@@ -608,7 +625,7 @@ const router = Router();
 
 router.use(devMiddleware(compiler, devMiddlewareOptions));
 
-const server = http.createServer((req, res) => {
+const server = createServer((req, res) => {
   router(req, res, finalhandler(req, res));
 });
 
@@ -618,10 +635,10 @@ server.listen(3000);
 ### Express
 
 ```js
-const { devMiddleware } = require("@rspack/dev-middleware");
-const express = require("express");
-const { rspack } = require("@rspack/core");
-const rspackConfig = require("./rspack.config.js");
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import express from "express";
+import rspackConfig from "./rspack.config.js";
 
 const compiler = rspack(rspackConfig);
 const devMiddlewareOptions = {
@@ -637,10 +654,10 @@ app.listen(3000, () => console.log("Example app listening on port 3000!"));
 ### Koa
 
 ```js
-const { devMiddleware } = require("@rspack/dev-middleware");
-const Koa = require("koa");
-const { rspack } = require("@rspack/core");
-const rspackConfig = require("./rspack.simple.config");
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import Koa from "koa";
+import rspackConfig from "./rspack.simple.config.js";
 
 const compiler = rspack(rspackConfig);
 const devMiddlewareOptions = {
@@ -648,7 +665,7 @@ const devMiddlewareOptions = {
 };
 const app = new Koa();
 
-app.use(middleware.koaWrapper(compiler, devMiddlewareOptions));
+app.use(devMiddleware.koaWrapper(compiler, devMiddlewareOptions));
 
 app.listen(3000);
 ```
@@ -656,10 +673,10 @@ app.listen(3000);
 ### Hapi
 
 ```js
-const Hapi = require("@hapi/hapi");
-const { devMiddleware } = require("@rspack/dev-middleware");
-const { rspack } = require("@rspack/core");
-const rspackConfig = require("./rspack.config.js");
+import Hapi from "@hapi/hapi";
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
+import rspackConfig from "./rspack.config.js";
 
 const compiler = rspack(rspackConfig);
 const devMiddlewareOptions = {};
@@ -688,10 +705,10 @@ process.on("unhandledRejection", (err) => {
 ### Hono
 
 ```js
+import { rspack } from "@rspack/core";
+import { devMiddleware } from "@rspack/dev-middleware";
 import { serve } from "@hono/node-server";
-import devMiddleware from "@rspack/dev-middleware";
 import { Hono } from "hono";
-import { rspack } from "@rspack/core";
 import rspackConfig from "./rspack.config.js";
 
 const compiler = rspack(rspackConfig);