Skip to content

Commit 651ef41

Browse files
authored
docs: update README with simplified badges and content (#20)
1 parent ab81ca3 commit 651ef41

1 file changed

Lines changed: 43 additions & 102 deletions

File tree

README.md

Lines changed: 43 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,13 @@
1-
<div align="center">
2-
<a href="https://github.com/webpack/webpack">
3-
<img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
4-
</a>
5-
</div>
6-
7-
[![npm][npm]][npm-url]
8-
[![node][node]][node-url]
9-
[![tests][tests]][tests-url]
10-
[![coverage][cover]][cover-url]
11-
[![discussion][discussion]][discussion-url]
12-
[![size][size]][size-url]
13-
141
# @rspack/dev-middleware
152

16-
An express-style development middleware for use with [Rspack](https://rspack.rs) and webpack-compatible compilers. It serves the files emitted by the compiler from memory.
3+
<p>
4+
<a href="https://npmjs.com/package/@rspack/dev-middleware?activeTab=readme"><img src="https://img.shields.io/npm/v/@rspack/dev-middleware?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" /></a>
5+
<a href="https://npmcharts.com/compare/@rspack/dev-middleware?minimal=true"><img src="https://img.shields.io/npm/dm/@rspack/dev-middleware.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="downloads" /></a>
6+
<a href="https://nodejs.org/en/about/previous-releases"><img src="https://img.shields.io/node/v/@rspack/dev-middleware.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="node version"></a>
7+
<a href="https://github.com/rstackjs/rspack-dev-middleware/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="license" /></a>
8+
</p>
9+
10+
An express-style development middleware for use with [Rspack](https://rspack.rs). It serves the files emitted by the compiler from memory.
1711

1812
This should be used for **development only**.
1913

@@ -26,7 +20,7 @@ Some of the benefits of using this middleware include:
2620

2721
## Getting Started
2822

29-
First thing's first, install the module:
23+
Install the module:
3024

3125
```bash
3226
# npm
@@ -42,10 +36,6 @@ yarn add -D @rspack/dev-middleware
4236
bun add -D @rspack/dev-middleware
4337
```
4438

45-
> [!WARNING]
46-
>
47-
> _We do not recommend installing this module globally._
48-
4939
## Usage
5040

5141
```js
@@ -54,7 +44,7 @@ const express = require("express");
5444
const { rspack } = require("@rspack/core");
5545

5646
const compiler = rspack({
57-
// webpack options
47+
// Rspack options
5848
});
5949

6050
const app = express();
@@ -86,8 +76,8 @@ See [below](#other-servers) for an example of use with fastify.
8676
| **[`publicPath`](#publicpath)** | `string` | `undefined` | The public path that the middleware is bound to. |
8777
| **[`stats`](#stats)** | `boolean\|string\|Object` | `stats` (from a configuration) | Stats options object or preset name. |
8878
| **[`serverSideRender`](#serversiderender)** | `boolean` | `undefined` | Instructs the module to enable or disable the server-side rendering mode. |
89-
| **[`writeToDisk`](#writetodisk)** | `boolean\|Function` | `false` | Instructs the module to write files to the configured location on disk as specified in your `webpack` configuration. |
90-
| **[`outputFileSystem`](#outputfilesystem)** | `Object` | [`memfs`](https://github.com/streamich/memfs) | Set the default file system which will be used by webpack as primary destination of generated files. |
79+
| **[`writeToDisk`](#writetodisk)** | `boolean\|Function` | `false` | Instructs the module to write files to the configured location on disk as specified in your Rspack configuration. |
80+
| **[`outputFileSystem`](#outputfilesystem)** | `Object` | [`memfs`](https://github.com/streamich/memfs) | Set the default file system which will be used by Rspack as primary destination of generated files. |
9181
| **[`modifyResponseData`](#modifyresponsedata)** | `Function` | `undefined` | Allows to set up a callback to change the response data. |
9282

9383
The middleware accepts an `options` Object. The following is a property reference for the Object.
@@ -229,7 +219,7 @@ Default: `output.publicPath` (from a configuration)
229219

230220
The public path that the middleware is bound to.
231221

232-
_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)._
222+
> Best Practice: use the same `publicPath` defined in your Rspack config.
233223
234224
### stats
235225

@@ -251,20 +241,18 @@ Please see [Server-Side Rendering](#server-side-rendering) for more information.
251241
Type: `Boolean|Function`
252242
Default: `false`
253243

254-
If `true`, the option will instruct the module to write files to the configured location on disk as specified in your `webpack` config file.
244+
If `true`, the option will instruct the module to write files to the configured location on disk as specified in your Rspack config file.
255245

256246
_Setting `writeToDisk: true` won't change the behavior of `@rspack/dev-middleware`, and bundle files accessed through the browser will still be served from memory._
257247

258-
This option provides the same capabilities as the [`WriteFilePlugin`](https://github.com/gajus/write-file-webpack-plugin/pulls).
259-
260248
This option also accepts a `Function` value, which can be used to filter which files are written to disk.
261249
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.
262250

263251
```js
264252
const { rspack } = require("@rspack/core");
265253

266254
const configuration = {
267-
/* Webpack configuration */
255+
/* Rspack configuration */
268256
};
269257
const compiler = rspack(configuration);
270258

@@ -278,11 +266,9 @@ middleware(compiler, {
278266
Type: `Object`
279267
Default: [memfs](https://github.com/streamich/memfs)
280268

281-
Set the default file system which will be used by webpack as primary destination of generated files.
269+
Set the default file system which will be used by Rspack as primary destination of generated files.
282270
This option isn't affected by the [writeToDisk](#writeToDisk) option.
283271

284-
You have to provide `.join()` and `mkdirp` method to the `outputFileSystem` instance manually for compatibility with `webpack@4`.
285-
286272
This can be done simply by using `path.join`:
287273

288274
```js
@@ -295,7 +281,7 @@ myOutputFileSystem.join = path.join.bind(path); // no need to bind
295281
myOutputFileSystem.mkdirp = mkdirp.bind(mkdirp); // no need to bind
296282

297283
const compiler = rspack({
298-
/* Webpack configuration */
284+
/* Rspack configuration */
299285
});
300286

301287
middleware(compiler, { outputFileSystem: myOutputFileSystem });
@@ -309,7 +295,7 @@ Allows to set up a callback to change the response data.
309295
const { rspack } = require("@rspack/core");
310296

311297
const configuration = {
312-
/* Webpack configuration */
298+
/* Rspack configuration */
313299
};
314300
const compiler = rspack(configuration);
315301

@@ -347,7 +333,7 @@ const express = require("express");
347333
const { rspack } = require("@rspack/core");
348334

349335
const compiler = rspack({
350-
/* Webpack configuration */
336+
/* Rspack configuration */
351337
});
352338

353339
const instance = middleware(compiler);
@@ -358,7 +344,7 @@ const app = new express();
358344
app.use(instance);
359345

360346
setTimeout(() => {
361-
// Says `webpack` to stop watch changes
347+
// Says Rspack to stop watch changes
362348
instance.close();
363349
}, 1000);
364350
```
@@ -382,7 +368,7 @@ const express = require("express");
382368
const { rspack } = require("@rspack/core");
383369

384370
const compiler = rspack({
385-
/* Webpack configuration */
371+
/* Rspack configuration */
386372
});
387373

388374
const instance = middleware(compiler);
@@ -394,7 +380,7 @@ app.use(instance);
394380

395381
setTimeout(() => {
396382
// After a short delay the configuration is changed and a banner plugin is added to the config
397-
new webpack.BannerPlugin("A new banner").apply(compiler);
383+
new rspack.BannerPlugin("A new banner").apply(compiler);
398384

399385
// Recompile the bundle with the banner plugin:
400386
instance.invalidate();
@@ -422,7 +408,7 @@ const express = require("express");
422408
const { rspack } = require("@rspack/core");
423409

424410
const compiler = rspack({
425-
/* Webpack configuration */
411+
/* Rspack configuration */
426412
});
427413

428414
const instance = middleware(compiler);
@@ -456,7 +442,7 @@ const express = require("express");
456442
const { rspack } = require("@rspack/core");
457443

458444
const compiler = rspack({
459-
/* Webpack configuration */
445+
/* Rspack configuration */
460446
});
461447

462448
const instance = middleware(compiler);
@@ -475,9 +461,9 @@ instance.waitUntilValid(() => {
475461

476462
## FAQ
477463

478-
### Avoid blocking requests to non-webpack resources.
464+
### Avoid blocking requests to non-Rspack resources.
479465

480-
Since `output.publicPath` and `output.filename`/`output.chunkFilename` can be dynamic, it's not possible to know which files are webpack bundles (and they public paths) and which are not, so we can't avoid blocking requests.
466+
Since `output.publicPath` and `output.filename`/`output.chunkFilename` can be dynamic, it's not possible to know which files are Rspack bundles (and they public paths) and which are not, so we can't avoid blocking requests.
481467

482468
But there is a solution to avoid it - mount the middleware to a non-root route, for example:
483469

@@ -487,7 +473,7 @@ const express = require("express");
487473
const { rspack } = require("@rspack/core");
488474

489475
const compiler = rspack({
490-
// webpack options
476+
// Rspack options
491477
});
492478

493479
const app = express();
@@ -529,13 +515,13 @@ const isObject = require("is-object");
529515
const { rspack } = require("@rspack/core");
530516

531517
const compiler = rspack({
532-
/* Webpack configuration */
518+
/* Rspack configuration */
533519
});
534520

535521
// eslint-disable-next-line new-cap
536522
const app = new express();
537523

538-
// This function makes server rendering of asset references consistent with different webpack chunk/entry configurations
524+
// This function makes server rendering of asset references consistent with different Rspack chunk/entry configurations
539525
function normalizeAssets(assets) {
540526
if (isObject(assets)) {
541527
return Object.values(assets);
@@ -578,32 +564,6 @@ app.use((req, res) => {
578564
});
579565
```
580566

581-
## Support
582-
583-
We do our best to keep Issues in the repository focused on bugs, features, and
584-
needed modifications to the code for the module. Because of that, we ask users
585-
with general support, "how-to", or "why isn't this working" questions to try one
586-
of the other support channels that are available.
587-
588-
Your first-stop-shop for support for webpack-dev-server should by the excellent
589-
[documentation][docs-url] for the module. If you see an opportunity for improvement
590-
of those docs, please head over to the [webpack.js.org repo][wjo-url] and open a
591-
pull request.
592-
593-
From there, we encourage users to visit the [webpack discussions][chat-url] and
594-
talk to the fine folks there. If your quest for answers comes up dry in chat,
595-
head over to [StackOverflow][stack-url] and do a quick search or open a new
596-
question. Remember; It's always much easier to answer questions that include your
597-
`webpack.config.js` and relevant files!
598-
599-
If you're twitter-savvy you can tweet [#webpack][hash-url] with your question
600-
and someone should be able to reach out and lend a hand.
601-
602-
If you have discovered a :bug:, have a feature suggestion, or would like to see
603-
a modification, please feel free to create an issue on Github. _Note: The issue
604-
template isn't optional, so please be sure not to remove it, and please fill it
605-
out completely._
606-
607567
## Other servers
608568

609569
Examples of use with other servers will follow here.
@@ -615,9 +575,9 @@ const http = require("node:http");
615575
const devMiddleware = require("@rspack/dev-middleware");
616576
const connect = require("connect");
617577
const { rspack } = require("@rspack/core");
618-
const webpackConfig = require("./webpack.config.js");
578+
const rspackConfig = require("./rspack.config.js");
619579

620-
const compiler = rspack(webpackConfig);
580+
const compiler = rspack(rspackConfig);
621581
const devMiddlewareOptions = {
622582
// options
623583
};
@@ -636,9 +596,9 @@ const devMiddleware = require("@rspack/dev-middleware");
636596
const finalhandler = require("finalhandler");
637597
const Router = require("router");
638598
const { rspack } = require("@rspack/core");
639-
const webpackConfig = require("./webpack.config.js");
599+
const rspackConfig = require("./rspack.config.js");
640600

641-
const compiler = rspack(webpackConfig);
601+
const compiler = rspack(rspackConfig);
642602
const devMiddlewareOptions = {
643603
// options
644604
};
@@ -661,9 +621,9 @@ server.listen(3000);
661621
const devMiddleware = require("@rspack/dev-middleware");
662622
const express = require("express");
663623
const { rspack } = require("@rspack/core");
664-
const webpackConfig = require("./webpack.config.js");
624+
const rspackConfig = require("./rspack.config.js");
665625

666-
const compiler = rspack(webpackConfig);
626+
const compiler = rspack(rspackConfig);
667627
const devMiddlewareOptions = {
668628
// options
669629
};
@@ -680,9 +640,9 @@ app.listen(3000, () => console.log("Example app listening on port 3000!"));
680640
const middleware = require("@rspack/dev-middleware");
681641
const Koa = require("koa");
682642
const { rspack } = require("@rspack/core");
683-
const webpackConfig = require("./webpack.simple.config");
643+
const rspackConfig = require("./rspack.simple.config");
684644

685-
const compiler = rspack(webpackConfig);
645+
const compiler = rspack(rspackConfig);
686646
const devMiddlewareOptions = {
687647
// options
688648
};
@@ -699,9 +659,9 @@ app.listen(3000);
699659
const Hapi = require("@hapi/hapi");
700660
const devMiddleware = require("@rspack/dev-middleware");
701661
const { rspack } = require("@rspack/core");
702-
const webpackConfig = require("./webpack.config.js");
662+
const rspackConfig = require("./rspack.config.js");
703663

704-
const compiler = rspack(webpackConfig);
664+
const compiler = rspack(rspackConfig);
705665
const devMiddlewareOptions = {};
706666

707667
const server = Hapi.server({ port: 3000, host: "localhost" });
@@ -733,9 +693,9 @@ Fastify interop will require the use of `fastify-express` instead of `middie` fo
733693
const devMiddleware = require("@rspack/dev-middleware");
734694
const fastify = require("fastify")();
735695
const { rspack } = require("@rspack/core");
736-
const webpackConfig = require("./webpack.config.js");
696+
const rspackConfig = require("./rspack.config.js");
737697

738-
const compiler = rspack(webpackConfig);
698+
const compiler = rspack(rspackConfig);
739699
const devMiddlewareOptions = {
740700
// options
741701
};
@@ -752,9 +712,9 @@ import { serve } from "@hono/node-server";
752712
import devMiddleware from "@rspack/dev-middleware";
753713
import { Hono } from "hono";
754714
import { rspack } from "@rspack/core";
755-
import webpackConfig from "./webpack.config.js";
715+
import rspackConfig from "./rspack.config.js";
756716

757-
const compiler = rspack(webpackConfig);
717+
const compiler = rspack(rspackConfig);
758718
const devMiddlewareOptions = {
759719
// options
760720
};
@@ -781,22 +741,3 @@ Please take a moment to read our contributing guidelines if you haven't yet done
781741
## License
782742

783743
[MIT](./LICENSE)
784-
785-
[npm]: https://img.shields.io/npm/v/%40rspack%2Fdev-middleware.svg
786-
[npm-url]: https://www.npmjs.com/package/@rspack/dev-middleware
787-
[node]: https://img.shields.io/node/v/%40rspack%2Fdev-middleware.svg
788-
[node-url]: https://nodejs.org
789-
[tests]: https://github.com/rstackjs/rspack-dev-middleware/actions/workflows/test.yml/badge.svg
790-
[tests-url]: https://github.com/rstackjs/rspack-dev-middleware/actions
791-
[cover]: https://codecov.io/gh/rstackjs/rspack-dev-middleware/branch/main/graph/badge.svg
792-
[cover-url]: https://codecov.io/gh/rstackjs/rspack-dev-middleware
793-
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
794-
[discussion-url]: https://github.com/webpack/webpack/discussions
795-
[size]: https://packagephobia.com/badge?p=%40rspack%2Fdev-middleware
796-
[size-url]: https://packagephobia.com/result?p=%40rspack%2Fdev-middleware
797-
[docs-url]: https://github.com/rstackjs/rspack-dev-middleware#readme
798-
[hash-url]: https://twitter.com/search?q=webpack
799-
[middleware-url]: https://github.com/rstackjs/rspack-dev-middleware
800-
[stack-url]: https://stackoverflow.com/questions/tagged/rspack-dev-middleware
801-
[chat-url]: https://github.com/webpack/webpack/discussions
802-
[wjo-url]: https://github.com/webpack/webpack.js.org

0 commit comments

Comments
 (0)