@modern-js/main-doc 2.60.0 → 2.60.1-alpha.0

package/docs/en/configure/app/tools/dev-server.mdx

@@ -4,6 +4,439 @@ title: devServer
 
 # tools.devServer
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/devServer.md';
+- **Type:** `Object`
+- **Default:** `{}`
 
-<Main />
+The config of DevServer can be modified through `tools.devServer`.
+
+:::tip
+Modern.js does not directly use [webpack-dev-server](https://webpack.js.org/api/webpack-dev-server/) or [@rspack/dev-server](https://www.rspack.dev/guide/dev-server.html), but implement DevServer based on [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware).
+:::
+
+### Options
+
+#### after
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.setupMiddlewares](https://modernjs.dev/en/configure/app/dev/setup-middlewares) instead.
+:::
+
+- **Type:** `Array`
+- **Default:** `[]`
+
+Provides the ability to execute custom middleware after all other middleware internally within the server.
+
+```js
+export default {
+  tools: {
+    devServer: {
+      after: [
+        async (req, res, next) => {
+          console.log('after dev middleware');
+          next();
+        },
+      ],
+    },
+  },
+};
+```
+
+`webpack-dev-server` uses Express as the server-side framework. Modern.js does not use any framework, and the `req` and `res` in the above middleware are all native Node objects. Therefore, the Express middleware used in `webpack-dev-server` may not be directly usable in Modern.js.
+
+If you want to migrate the Express middleware used in `webpack-dev-server`, you can use the following method to pass the Express app as middleware:
+
+```js
+import expressMiddleware from 'my-express-middleware';
+import express from 'express';
+
+// init Express app
+const app = express();
+app.use(expressMiddleware);
+
+export default {
+  tools: {
+    devServer: {
+      after: [app],
+    },
+  },
+};
+```
+
+#### before
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.setupMiddlewares](https://modernjs.dev/en/configure/app/dev/setup-middlewares) instead.
+:::
+
+- **Type:** `Array`
+- **Default:** `[]`
+
+Provides the ability to execute custom middleware prior to all other middleware internally within the server.
+
+```js
+export default {
+  tools: {
+    devServer: {
+      before: [
+        async (req, res, next) => {
+          console.log('before dev middleware');
+          next();
+        },
+      ],
+    },
+  },
+};
+```
+
+#### client
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.client](https://modernjs.dev/en/configure/app/dev/client) instead.
+:::
+
+- **Type:**
+
+```ts
+{
+    /** Specify a protocol to use */
+    protocol?: string;
+    /** The path which the middleware is serving the event stream on */
+    path?: string;
+    /** Specify a port number to listen for requests on */
+    port?: string;
+    /** Specify a host to use */
+    host?: string;
+}
+```
+
+- **Default:**
+
+```js
+const defaultConfig = {
+  path: '/webpack-hmr',
+  // By default it is set to the port number of the dev server
+  port: '',
+  // By default it is set to "location.hostname"
+  host: '',
+  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
+  protocol: '',
+};
+```
+
+The config of HMR client, which are usually used to set the WebSocket URL of HMR.
+
+#### compress
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to enable gzip compression for served static assets.
+
+If you want to disable the gzip compression, you can set `compress` to `false`:
+
+```ts
+export default {
+  tools: {
+    devServer: {
+      compress: false,
+    },
+  },
+};
+```
+
+#### devMiddleware
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.writeToDisk](https://modernjs.dev/en/configure/app/dev/write-to-disk) instead.
+:::
+
+- **Type:**
+
+```js
+{
+  writeToDisk: boolean | ((filename: string) => boolean);
+}
+```
+
+- **Default:**
+
+```js
+{
+  writeToDisk: (file: string) => !file.includes('.hot-update.'),
+}
+```
+
+The config of devMiddleware. Current options is the subset of [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware).
+
+#### headers
+
+- **Type:** `Record<string, string>`
+- **Default:** `undefined`
+
+Adds headers to all responses.
+
+```js
+export default {
+  tools: {
+    devServer: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+#### historyApiFallback
+
+- **Type:** `boolean | ConnectHistoryApiFallbackOptions`
+- **Default:** `false`
+
+The index.html page will likely have to be served in place of any 404 responses. Enable `devServer.historyApiFallback` by setting it to `true`:
+
+```js
+export default {
+  tools: {
+    devServer: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+For more options and information, see the [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) documentation.
+
+#### hot
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.hmr](https://modernjs.dev/en/configure/app/dev/hmr) instead.
+:::
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Enable [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) feature.
+
+#### https
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.https](https://modernjs.dev/en/configure/app/dev/https) instead.
+:::
+
+- **Type:** `boolean | { key: string; cert: string }`
+- **Default:** `false`
+
+By default, DevServer will be served over HTTP. It can optionally be served over HTTPS by setting `devServer.https` to `true`, and will disable the HTTP server.
+
+You can also manually pass in the certificate and corresponding private key required by the HTTPS server:
+
+```ts
+export default {
+  tools: {
+    devServer: {
+      https: {
+        key: fs.readFileSync('certificates/private.pem'),
+        cert: fs.readFileSync('certificates/public.pem'),
+      },
+    },
+  },
+};
+```
+
+#### liveReload
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.liveReload](https://modernjs.dev/en/configure/app/dev/live-reload) instead.
+:::
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+By default, the DevServer will reload/refresh the page when file changes are detected (`devServer.hot` option must be disabled in order for liveReload to take effect). Disable `devServer.liveReload` by setting it to `false`.
+
+#### setupMiddlewares
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use [dev.setupMiddlewares](https://modernjs.dev/en/configure/app/dev/setup-middlewares) instead.
+:::
+
+- **Type:**
+
+```js
+Array<
+  (
+    middlewares: {
+      unshift: (...handlers: RequestHandler[]) => void;
+      push: (...handlers: RequestHandler[]) => void;
+    },
+    server: {
+      sockWrite: (
+        type: string,
+        data?: string | boolean | Record<string, any>,
+      ) => void;
+    },
+  ) => void
+>;
+```
+
+- **Default:** `undefined`
+
+Provides the ability to execute a custom function and apply custom middlewares.
+
+The order among several different types of middleware is: `devServer.before` => `unshift` => internal middlewares => `push` => `devServer.after`.
+
+```js
+export default {
+  tools: {
+    devServer: {
+      setupMiddlewares: [
+        (middlewares, server) => {
+          middlewares.unshift((req, res, next) => {
+            next();
+          });
+
+          middlewares.push((req, res, next) => {
+            next();
+          });
+        },
+      ],
+    },
+  },
+};
+```
+
+It is possible to use some server api to meet special scenario requirements:
+
+- sockWrite. Allow send some message to hmr client, and then the hmr client will take different actions depending on the message type. If you send a "content changed" message, the page will reload.
+
+```js
+export default {
+  tools: {
+    devServer: {
+      setupMiddlewares: [
+        (middlewares, server) => {
+          // add custom watch & trigger page reload when change
+          watcher.on('change', changed => {
+            server.sockWrite('content-changed');
+          });
+        },
+      ],
+    },
+  },
+};
+```
+
+#### proxy
+
+- **Type:** `Record<string, string> | Record<string, ProxyDetail>`
+- **Default:** `undefined`
+
+Proxying some URLs.
+
+```js
+export default {
+  tools: {
+    devServer: {
+      proxy: {
+        '/api': 'http://localhost:3000',
+      },
+    },
+  },
+};
+```
+
+A request to /api/users will now proxy the request to http://localhost:3000/api/users.
+
+If you don't want /api to be passed along, we need to rewrite the path:
+
+```js
+export default {
+  tools: {
+    devServer: {
+      proxy: {
+        '/api': {
+          target: 'http://localhost:3000',
+          pathRewrite: { '^/api': '' },
+        },
+      },
+    },
+  },
+};
+```
+
+The DevServer Proxy makes use of the [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x) package. Check out its documentation for more advanced usages.
+
+The full type definition of DevServer Proxy is:
+
+```ts
+import type { Options as HttpProxyOptions } from 'http-proxy-middleware';
+
+type Filter = string | string[] | ((pathname: string, req: Request) => boolean);
+
+type ProxyDetail = HttpProxyOptions & {
+  bypass?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+    proxyOptions: ProxyOptions,
+  ) => string | undefined | null | false;
+  context?: Filter;
+};
+
+type ProxyOptions =
+  | Record<string, string>
+  | Record<string, ProxyDetail>
+  | ProxyDetail[]
+  | ProxyDetail;
+```
+
+In addition to the http-proxy-middleware option, we also support the bypass and context configuration:
+
+- bypass: bypass the proxy based on the return value of a function.
+  - Return `null` or `undefined` to continue processing the request with proxy.
+  - Return `false` to produce a 404 error for the request.
+  - Return a path to serve from, instead of continuing to proxy the request.
+- context: If you want to proxy multiple, specific paths to the same target, you can use an array of one or more objects with a context property.
+
+```js
+// custom bypass
+export default {
+  tools: {
+    devServer: {
+      proxy: {
+        '/api': {
+          target: 'http://localhost:3000',
+          bypass: function (req, res, proxyOptions) {
+            if (req.headers.accept.indexOf('html') !== -1) {
+              console.log('Skipping proxy for browser request.');
+              return '/index.html';
+            }
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+```js
+// proxy multiple
+export default {
+  tools: {
+    devServer: {
+      proxy: [
+        {
+          context: ['/auth', '/api'],
+          target: 'http://localhost:3000',
+        },
+      ],
+    },
+  },
+};
+```
+
+#### watch
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to watch files change in directories such as `mock/`, `server/`, `api/`.

package/docs/en/configure/app/tools/esbuild.mdx

@@ -16,7 +16,7 @@ Please refer to [「Use Rspack」](/guides/advanced-features/rspack-start.html)
 
 ## Introduction
 
-import Esbuild from '@modern-js/builder-doc/docs/en/shared/esbuild.md';
+import Esbuild from '@site-docs-en/components/esbuild.mdx';
 
 <Esbuild />
 

package/docs/en/configure/app/tools/html-plugin.mdx

@@ -1,9 +1,28 @@
 ---
 title: htmlPlugin
+configName: tools.htmlPlugin
 ---
 
 # tools.htmlPlugin
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/htmlPlugin.md';
+- **Type:** `boolean | Object | Function`
+- **Default:**
 
-<Main />
+```js
+const defaultOptions = {
+  meta, // 对应 `html.meta` 配置
+  title, // 对应 `html.title` 配置
+  inject, // 对应 `html.inject` 配置
+  favicon, // 对应 `html.favicon` 配置
+  template, // 对应 `html.template` 配置
+  filename, // 基于 `output.distPath` 和 `entryName` 生成
+  templateParameters, // 对应 `html.templateParameters` 配置
+  chunks: [entryName],
+};
+```
+
+The configs of [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) or [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) can be modified through `tools.htmlPlugin`.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/tools/less.mdx

@@ -4,6 +4,82 @@ title: less
 
 # tools.less
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/less.md';
+- **Type:** `Object | Function`
+- **Default:**
 
-<Main />
+```js
+const defaultOptions = {
+  lessOptions: {
+    javascriptEnabled: true,
+  },
+  // CSS Source Map enabled by default in development environment
+  sourceMap: isDev,
+};
+```
+
+You can modify the config of [less-loader](https://github.com/webpack-contrib/less-loader) via `tools.less`.
+
+### Object Type
+
+When `tools.less` is configured as `Object` type, it is merged with the default config through Object.assign in a shallow way. It should be noted that `lessOptions` is merged through deepMerge in a deep way. For example:
+
+```js
+export default {
+  tools: {
+    less: {
+      lessOptions: {
+        javascriptEnabled: false,
+      },
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.less` is a Function, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For example:
+
+```js
+export default {
+  tools: {
+    less(config) {
+      // Modify the config of lessOptions
+      config.lessOptions = {
+        javascriptEnabled: false,
+      };
+    },
+  },
+};
+```
+
+### Modifying Less Version
+
+In some scenarios, if you need to use a specific version of Less instead of the built-in Less v4 in Modern.js, you can install the desired Less version in your project and set it up using the `implementation` option of the `less-loader`.
+
+```js
+export default {
+  tools: {
+    less: {
+      implementation: require('less'),
+    },
+  },
+};
+```
+
+### Util Function
+
+#### addExcludes
+
+- **Type:** `(excludes: RegExp | RegExp[]) => void`
+
+Used to specify which files `less-loader` does not compile, You can pass in one or more regular expressions to match the path of less files, for example:
+
+```js
+export default {
+  tools: {
+    less(config, { addExcludes }) {
+      addExcludes(/node_modules/);
+    },
+  },
+};
+```

package/docs/en/configure/app/tools/minify-css.mdx

@@ -4,6 +4,54 @@ title: minifyCss
 
 # tools.minifyCss
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/minifyCss.md';
+- **Type:** `Object | Function | undefined`
+- **Default:**
 
-<Main />
+```js
+const defaultOptions = {
+  minimizerOptions: {
+    preset: [
+      'default',
+      {
+        mergeLonghand: false,
+      },
+    ],
+  },
+};
+```
+
+When building for production, Modern.js will minimize the CSS code through [css-minimizer-webpack-plugin](https://github.com/webpack-contrib/css-minimizer-webpack-plugin). The config of [css-minimizer-webpack-plugin](https://github.com/webpack-contrib/css-minimizer-webpack-plugin) can be modified via `tools.minifyCss`.
+
+### Object Type
+
+When `tools.minifyCss` is `Object` type, it will be merged with the default config via `Object.assign`.
+
+For example, modify the `preset` config of [cssnano](https://cssnano.co/):
+
+```js
+export default {
+  tools: {
+    minifyCss: {
+      minimizerOptions: {
+        preset: require.resolve('cssnano-preset-simple'),
+      },
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.minifyCss` is `Function` type, the default config is passed in as the first parameter, the config object can be modified directly, or a value can be returned as the final result.
+
+```js
+export default {
+   tools: {
+    minifyCss: options => {
+      options.minimizerOptions = {
+        preset: require.resolve('cssnano-preset-simple'),
+      },
+    }
+  }
+};
+```

package/docs/en/configure/app/tools/postcss.mdx

@@ -1,9 +1,37 @@
 ---
 title: postcss
+configName: tools.postcss
 ---
 
 # tools.postcss
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/postcss.md';
+- **Type:** `Object | Function`
+- **Default:**
 
-<Main />
+```js
+const defaultOptions = {
+  postcssOptions: {
+    plugins: [
+      // 以下插件默认启用
+      require('postcss-nesting'),
+      require('postcss-media-minmax'),
+      require('postcss-flexbugs-fixes'),
+      require('autoprefixer')({
+        flexbox: 'no-2009',
+      }),
+      // 以下插件仅在需要兼容低版本浏览器时启用
+      require('postcss-custom-properties'),
+      require('postcss-initial'),
+      require('postcss-page-break'),
+      require('postcss-font-variant'),
+    ],
+    // 默认在开发环境下启用 CSS 的 Source Map
+    sourceMap: isDev,
+  },
+};
+```
+Modern.js integrates PostCSS by default, you can configure [postcss-loader](https://github.com/webpack-contrib/postcss-loader) through `tools.postcss`.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/tools/pug.mdx

@@ -4,6 +4,51 @@ title: pug
 
 # tools.pug
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/pug.md';
+- **Type:** `true | Object | Function | undefined`
+- **Default:** `false`
 
-<Main />
+Configure the [Pug](https://pugjs.org/) template engine.
+
+### Boolean Type
+
+Pug template engine is not enabled by default, you can enable it by setting `tools.pug` to `true`.
+
+```ts
+export default {
+  tools: {
+    pug: true,
+  },
+};
+```
+
+When enabled, you can use `index.pug` as the template file in `html.template` config.
+
+### Object Type
+
+When `tools.terser` is `Object` type, you can passing the Pug options:
+
+```ts
+export default {
+  tools: {
+    pug: {
+      doctype: 'xml',
+    },
+  },
+};
+```
+
+For detailed options, please refer to [Pug API Reference](https://pugjs.org/api/reference.html#options).
+
+### Function Type
+
+When `tools.pug` is `Function` type, the default configuration is passed in as the first parameter, the configuration object can be modified directly, or a value can be returned as the final result.
+
+```ts
+export default {
+  tools: {
+    pug(config) {
+      config.doctype = 'xml';
+    },
+  },
+};
+```