@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.97 → 3.5.0-ultramodern.99

package/docs/configure/app/bff/prefix.mdx

@@ -0,0 +1,33 @@
+---
+title: prefix
+---
+
+# bff.prefix
+
+- **Type:** `string`
+- **Default:** `/api`
+
+import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+By default, the prefix for accessing routes in the BFF API directory is `/api`, as shown in the following directory structure:
+
+```bash
+api
+└── hello.ts
+```
+
+The route corresponding to `api/hello.ts` when accessed is `localhost:8080/api/hello`.
+
+This configuration option can modify the default route prefix:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    prefix: '/api-demo',
+  },
+});
+```
+
+The corresponding route for `api/hello.ts` when accessed is `localhost:8080/api-demo/hello`.

package/docs/configure/app/bff/runtime-framework.mdx

@@ -0,0 +1,30 @@
+---
+title: runtimeFramework
+---
+
+# bff.runtimeFramework
+
+- **Type:** `'hono' | 'effect'`
+- **Default:** `'effect'`
+
+import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+Controls which runtime framework Modern.js uses for BFF routing.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+  },
+});
+```
+
+- Set to `'effect'` to run BFF only from `api/index` (Effect HttpApi runtime).
+- Set to `'hono'` to run BFF only from file-convention handlers under `api/lambda/**`.
+
+There is no implicit fallback between runtimes. Choose one runtime mode per app.
+Generated UltraModern apps use strict Effect APIs by default and set
+`bff.effect.strictEffectApproach: true`; `hono` and `api/lambda/**` are not
+valid generated UltraModern HTTP API paths.

package/docs/configure/app/builder-plugins.mdx

@@ -0,0 +1,70 @@
+---
+sidebar_position: 21
+---
+
+# builderPlugins
+
+- **Type:** `RsbuildPlugin[]`
+- **Default:** `[]`
+
+Used to configure the Rsbuild plugin.
+
+Rsbuild is the build tool of Modern.js, please read [Build Engine](/guides/concept/builder) for background. If you want to know how to write Rsbuild plugins, you can refer to [Rsbuild - Plugin System](https://v2.rsbuild.rs/plugins/dev/index).
+
+## Precautions
+
+This option **is used to configure the Rsbuild plugins**. If you need to configure other types of plugins, please select the corresponding configs:
+
+- Use [plugins](/configure/app/plugins) to configure Modern.js framework plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) to configure Rspack plugins.
+
+## When to use
+
+In most scenarios, we recommend you to use the Modern.js framework plugin, which can be registered through the [plugins](/configure/app/plugins) config. Because the API provided by the framework plugin is richer and more capable, while the API provided by the Rsbuild plugin can only be used to build scenes.
+
+When you need to reference some existing Rsbuild plugins (and there is no related capability in Modern.js), or reuse Rsbuild plugins between different frameworks, you can use the `builderPlugins` field to register them.
+
+## Example
+
+Below is an example of using the Rsbuild plugin.
+
+### Using plugins on npm
+
+To use a plugin on npm, you need to install the plugin through the package manager and import it.
+
+```ts title="modern.config.ts"
+import myRsbuildPlugin from 'my-rsbuild-plugin';
+
+export default defineConfig({
+  builderPlugins: [myRsbuildPlugin()],
+});
+```
+
+### Using local plugins
+
+Use the plugin in the local code repository, you can import it directly through the relative path import.
+
+```ts title="modern.config.ts"
+import myRsbuildPlugin from './plugin/myRsbuildPlugin';
+
+export default defineConfig({
+  builderPlugins: [myRsbuildPlugin()],
+});
+```
+
+### Plugin configuration options
+
+If the plugin provides some custom configuration options, you can pass in the configuration through the parameters of the plugin function.
+
+```ts title="modern.config.ts"
+import myRsbuildPlugin from 'my-rsbuild-plugin';
+
+export default defineConfig({
+  builderPlugins: [
+    myRsbuildPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/docs/configure/app/dev/asset-prefix.mdx

@@ -0,0 +1,18 @@
+---
+title: assetPrefix
+---
+
+# dev.assetPrefix
+
+- **Type:** `boolean | string | 'auto'`
+- **Default:** `'/'`
+
+This configuration item is used to set the URL prefix of static resources in **development mode**.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.assetPrefix" />
+
+:::warning
+Please note that this configuration item is only applicable in development mode. In production mode, please use the [output.assetPrefix](/configure/app/output/asset-prefix) configuration item for setting.
+:::

package/docs/configure/app/dev/before-start-url.mdx

@@ -0,0 +1,21 @@
+---
+title: beforeStartUrl
+---
+
+# dev.beforeStartUrl
+
+- **Type:** `() => Promise<void> | void`
+- **Default:** `undefined`
+
+`dev.beforeStartUrl` is used to execute a callback function before opening the `startUrl`, this config needs to be used together with `dev.startUrl`.
+
+```js
+export default {
+  dev: {
+    startUrl: true,
+    beforeStartUrl: async () => {
+      await doSomeThing();
+    },
+  },
+};
+```

package/docs/configure/app/dev/client.mdx

@@ -0,0 +1,45 @@
+---
+title: client
+---
+
+# dev.client
+
+- **Type:**
+
+```ts
+type Client = {
+  // The protocol name for the WebSocket request
+  protocol?: 'ws' | 'wss';
+  // The path for the WebSocket request
+  path?: string;
+  // The port number for the WebSocket request
+  port?: string | number;
+  // The host for the WebSocket request
+  host?: string;
+  // The maximum number of reconnection attempts after a WebSocket request is disconnected.
+  reconnect?: number;
+  // Whether to display an error overlay in the browser when a compilation error occurs
+  overlay?: boolean;
+};
+```
+
+- **Default:**
+
+```js
+const defaultConfig = {
+  path: '/webpack-hmr',
+  port: '<port>',
+  // By default it is set to "location.hostname"
+  host: '',
+  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
+  protocol: undefined,
+  reconnect: 100,
+  overlay: false,
+};
+```
+
+Configure the client code injected by Modern.js during the development process. This can be used to set the WebSocket URL for HMR.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.client" />

package/docs/configure/app/dev/hmr.mdx

@@ -0,0 +1,14 @@
+---
+title: hmr
+---
+
+# dev.hmr
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to enable Hot Module Replacement.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.hmr" />

package/docs/configure/app/dev/host.mdx

@@ -0,0 +1,22 @@
+---
+title: host
+---
+
+# dev.host
+
+- **Type:** `string`
+- **Default:** `0.0.0.0`
+
+Specify the host that the dev server listens to.
+
+By default, the dev server will listen to `0.0.0.0`, which means listening to all network interfaces, including `localhost` and public network addresses.
+
+If you want the dev server to listen only on `localhost`, you can set it to:
+
+```ts
+export default {
+  dev: {
+    host: 'localhost',
+  },
+};
+```

package/docs/configure/app/dev/https.mdx

@@ -0,0 +1,81 @@
+---
+title: https
+---
+
+# dev.https
+
+- **Type:** `boolean | { key: string; cert: string }`
+- **Default:** `false`
+
+After configuring this option, you can enable HTTPS Dev Server, and disabling the HTTP Dev Server.
+
+HTTP:
+
+```bash
+  > Local: http://localhost:8080/
+  > Network: http://192.168.0.1:8080/
+```
+
+HTTPS:
+
+```bash
+  > Local: https://localhost:8080/
+  > Network: https://192.168.0.1:8080/
+```
+
+#### Automatically generate certificates
+
+You can directly set `https` to `true`, Modern.js will automatically generate the HTTPS certificate based on [devcert](https://github.com/davewasmer/devcert).
+
+When using this method, you need to manually install the [devcert](https://github.com/davewasmer/devcert) dependency in your project:
+
+```bash
+# npm
+npm install devcert@1.2.2 -D
+
+# yarn
+yarn add devcert@1.2.2 -D
+
+# pnpm
+pnpm add devcert@1.2.2 -D
+```
+
+Then configure `dev.https` to `true`:
+
+```ts
+export default {
+  dev: {
+    https: true,
+  },
+};
+```
+
+The devcert has some limitations, it does not currently support IP addresses yet.
+
+:::tip
+The https proxy automatically installs the certificate and needs root authority, please enter the password according to the prompt.
+**The password is only used to trust the certificate, and will not be leaked or be used elsewhere**.
+:::
+
+#### Manually set the certificate
+
+You can also manually pass in the certificate and the private key required in the `dev.https` option. This parameter will be directly passed to the createServer method of the https module in Node.js.
+
+For details, please refer to [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener).
+
+```ts
+import fs from 'fs';
+
+export default {
+  dev: {
+    https: {
+      key: fs.readFileSync('certificates/private.pem'),
+      cert: fs.readFileSync('certificates/public.pem'),
+    },
+  },
+};
+```
+
+#### Clean up cert cache
+
+The certificate created by devcert is saved in `~/Library/Application\ Support/devcert`. You may do some cleanup if needed.

package/docs/configure/app/dev/lazy-compilation.mdx

@@ -0,0 +1,45 @@
+---
+title: lazyCompilation
+---
+
+# dev.lazyCompilation
+
+- **Type:**
+
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      /**
+       * Enable lazy compilation for entries.
+       */
+      entries?: boolean;
+      /**
+       * Enable lazy compilation for dynamic imports.
+       */
+      imports?: boolean;
+      /**
+       * Specify which imported modules should be lazily compiled.
+       */
+      test?: RegExp | ((m: Module) => boolean);
+      /**
+       * The path to a custom runtime code that overrides the default lazy compilation client.
+       */
+      client?: string;
+      /**
+       * Tells the client the server URL that needs to be requested.
+       */
+      serverUrl?: string;
+    };
+```
+
+- **Default:** `false`
+
+Enable lazy compilation (compilation on demand), implemented based on Rspack's [lazy compilation](https://rspack.rs/guide/features/lazy-compilation) feature.
+
+import RsbuildLink from '@site/src/components/RsbuildLink';
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to <RsbuildLink configName="dev.lazyCompilation"/>。
+In Rspack build mode,
+:::

package/docs/configure/app/dev/live-reload.mdx

@@ -0,0 +1,14 @@
+---
+title: liveReload
+---
+
+# dev.liveReload
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to reload the page when source files are changed.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.liveReload" />

package/docs/configure/app/dev/mock-dir.mdx

@@ -0,0 +1,35 @@
+---
+title: mockDir
+---
+
+# dev.mockDir
+
+- **Type:** `string`
+- **Default:** `'./config/mock'`
+
+Sets the directory containing the Mock API entry file. Relative paths are
+resolved from the application directory, and absolute paths are also supported.
+Modern.js loads `index.ts` or `index.js` from this directory during development.
+
+For example, move the Mock API entry to `mocks/index.ts`:
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  dev: {
+    mockDir: './mocks',
+  },
+});
+```
+
+This is also useful in a monorepo when multiple applications share one Mock
+directory:
+
+```js title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    mockDir: '../../shared/mocks',
+  },
+});
+```

package/docs/configure/app/dev/progress-bar.mdx

@@ -0,0 +1,23 @@
+---
+title: progressBar
+---
+
+# dev.progressBar
+
+- **Type:**
+
+```ts
+type ProgressBar =
+  | boolean
+  | {
+      id?: string;
+    };
+```
+
+- **Default:** true
+
+Whether to display progress bar during compilation.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.progressBar" />

package/docs/configure/app/dev/server.mdx

@@ -0,0 +1,128 @@
+---
+title: server
+---
+
+# dev.server
+
+- **Type:** `Object`
+- **Default:** `{}`
+
+The config of DevServer can be modified through `dev.server`.
+
+### 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 {
+  dev: {
+    server: {
+      compress: false,
+    },
+  },
+};
+```
+
+For more details, please refer to the [Rsbuild - server.compress](https://v2.rsbuild.rs/config/server/compress) documentation.
+
+### headers
+
+- **Type:** `Record<string, string>`
+- **Default:** `undefined`
+
+Adds headers to all responses.
+
+```js
+export default {
+  dev: {
+    server: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+For more details, please refer to the [Rsbuild - server.headers](https://v2.rsbuild.rs/config/server/headers) documentation.
+
+### historyApiFallback
+
+- **Type:** `boolean | ConnectHistoryApiFallbackOptions`
+- **Default:** `false`
+
+The index.html page will likely have to be served in place of any 404 responses. Enable `dev.server.historyApiFallback` by setting it to `true`:
+
+```js
+export default {
+  dev: {
+    server: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+For more configuration options, please refer to the [Rsbuild - server.historyApiFallback](https://v2.rsbuild.rs/config/server/history-api-fallback) documentation.
+
+### watch
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to watch files change in directories such as `mock/`, `server/`, `api/`.
+
+For more details, please refer to the [Rsbuild - dev.watchFiles](https://v2.rsbuild.rs/config/dev/watch-files) documentation.
+
+### cors
+
+- **Type:** `boolean | import('cors').CorsOptions`
+
+Configure CORS (Cross-Origin Resource Sharing) for the development server.
+
+The default configuration for `cors` in Modern.js follows Rsbuild's defaults:
+
+```ts
+const defaultAllowedOrigins =
+  /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/;
+
+const defaultOptions = {
+  // Default allowed:
+  // - localhost
+  // - 127.0.0.1
+  // - [::1]
+  origin: defaultAllowedOrigins,
+};
+```
+
+For more configuration options and detailed usage, please refer to the [Rsbuild - server.cors](https://v2.rsbuild.rs/config/server/cors) documentation.
+
+### proxy
+
+- **Type:** `ProxyOptions[] | Record<string, string | ProxyOptions>`
+- **Default:** `undefined`
+
+Configure proxy rules for the dev server, and forward requests to the specified service.
+
+```js
+export default {
+  dev: {
+    server: {
+      proxy: {
+        // http://localhost:8080/api -> https://example.com/api
+        // http://localhost:8080/api/foo -> https://example.com/api/foo
+        '/api': 'https://example.com',
+      },
+    },
+  },
+};
+```
+
+:::tip
+This option is the same as Rsbuild's `server.proxy` option, see [Rsbuild - server.proxy](https://v2.rsbuild.rs/config/server/proxy) for detailed usage.
+:::

package/docs/configure/app/dev/setup-middlewares.mdx

@@ -0,0 +1,36 @@
+---
+title: setupMiddlewares
+---
+
+# dev.setupMiddlewares
+
+- **Type:**
+
+```ts
+type RequestHandler = (req: any, res: any, next: () => void) => void;
+
+type ExposeServerApis = {
+  sockWrite: (
+    type: string,
+    data?: string | boolean | Record<string, any>,
+  ) => void;
+};
+
+type SetupMiddlewares = Array<
+  (
+    middlewares: {
+      unshift: (...handlers: RequestHandler[]) => void;
+      push: (...handlers: RequestHandler[]) => void;
+    },
+    server: ExposeServerApis,
+  ) => void
+>;
+```
+
+- **Default:** `undefined`
+
+Provides the ability to execute a custom function and apply custom middlewares.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.setupMiddlewares" />

package/docs/configure/app/dev/start-url.mdx

@@ -0,0 +1,53 @@
+---
+title: startUrl
+---
+
+# dev.startUrl
+
+- **Type:** `boolean | string | string[] | undefined`
+- **Default:** `undefined`
+
+`dev.startUrl` is used to set the URL of the page that automatically opens in the browser when Dev Server starts.
+
+By default, no page will be opened.
+
+You can set it to the following values:
+
+```js
+export default {
+  dev: {
+    // Open the project's default preview page, equivalent to `http://localhost:<port>`
+    startUrl: true,
+    // Open the specified page
+    startUrl: 'http://localhost:8080',
+    // Open multiple pages
+    startUrl: ['http://localhost:8080', 'http://localhost:8080/about'],
+  },
+};
+```
+
+### Port placeholder
+
+Since the port number may change, you can use the `<port>` placeholder to refer to the current port number, and Modern.js will automatically replace the placeholder with the actual listening port number.
+
+```js
+export default {
+  dev: {
+    startUrl: 'http://localhost:<port>/home',
+  },
+};
+```
+
+### Open the specified browser
+
+On MacOS, you can open the specified browser when Dev Server starts, by set environment variable `BROWSER`, support values:
+
+- Google Chrome Canary
+- Google Chrome Dev
+- Google Chrome Beta
+- Google Chrome
+- Microsoft Edge
+- Brave Browser
+- Vivaldi
+- Chromium
+