@modern-js/app-tools 3.6.0 → 3.8.0

package/docs/configure/app/tools/ts-checker.md

@@ -0,0 +1,109 @@
+# tools.tsChecker
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultOptions = {
+  typescript: {
+    // set 'readonly' to avoid emitting tsbuildinfo,
+    // as the generated tsbuildinfo will break ts-checker-rspack-plugin
+    mode: 'readonly',
+    // enable build when using project reference
+    build: useReference,
+    // avoid OOM issue
+    memoryLimit: 8192,
+    // use tsconfig of user project
+    configFile: tsconfigPath,
+    // resolve the default TypeScript package from user project
+    resolveRoot: rootPath,
+  },
+  issue: {
+    // ignore type errors from node_modules
+    exclude: [({ file = '' }) => /[\\/]node_modules[\\/]/.test(file)],
+  },
+  logger: {
+    log() {
+      // do nothing
+      // we only want to display error messages
+    },
+    error(message: string) {
+      console.error(
+        message
+          .replace(/ERROR/g, 'Type Error')
+          .replace(/WARNING/g, 'Type Warning'),
+      );
+    },
+  },
+},
+```
+
+By default, the [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) is enabled for type checking. You can use `output.disableTsChecker` config to disable it.
+
+## Example
+
+### Object Type
+
+When the value of `tsChecker` is an object, it will be deeply merged with the default configuration.
+
+```ts
+export default {
+  tools: {
+    tsChecker: {
+      issue: {
+        exclude: [({ file = '' }) => /[\\/]some-folder[\\/]/.test(file)],
+      },
+    },
+  },
+};
+```
+
+### Function Type
+
+When the value of `tsChecker` is a function, the default configuration will be passed as the first argument. You can directly modify the configuration object or return an object as the final configuration.
+
+```ts
+export default {
+  tools: {
+    tsChecker(options) {
+      options.async = false;
+      return options;
+    },
+  },
+};
+```
+
+> Please refer to [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) for more details.
+
+## TypeScript 7+ Support
+
+`tools.tsChecker` supports the native checker included in TypeScript 7+. This capability is provided by [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin), which is integrated by [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check), and can reduce type-checking time on large projects.
+
+Install TypeScript >= 7.0.0 to enable `tsgo` automatically:
+
+
+```sh [npm]
+npm install typescript@latest -D
+```
+
+```sh [yarn]
+yarn add typescript@latest -D
+```
+
+```sh [pnpm]
+pnpm add typescript@latest -D
+```
+
+```sh [bun]
+bun add typescript@latest -D
+```
+
+```sh [deno]
+deno add npm:typescript@latest -D
+```
+
+When `tsgo` is enabled and `typescript.typescriptPath` is set manually, it must point to an absolute TypeScript 7+ `typescript/package.json` path or the legacy `@typescript/native-preview/package.json` path.
+
+> The `@typescript/native-preview` path is kept only for compatibility. New setups should use TypeScript 7+ from the standard `typescript` package.
+
+For supported options and limitations, please refer to [ts-checker-rspack-plugin - TypeScript 7+ support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-7-support).

package/docs/configure/app/usage.md

@@ -0,0 +1,276 @@
+# Configuration
+
+There are three types of configurations in Modern.js: Compile configuration, Runtime configuration, and Server Runtime configuration.
+
+**Compile configuration** can be configured in two locations:
+
+- The `modern.config.(ts|js|mjs)` file at the root path
+- The `package.json` file
+
+:::info
+Modern.js does not support configuring the same configuration item in both `package.json` and `modern.config.ts` simultaneously. It is recommended to configure it in `modern.config.ts`. If Modern.js detects conflicts due to duplicate configurations, it will throw a warning.
+:::
+
+**Runtime configuration** can be configured in the `src/modern.runtime.(ts|js|mjs)` file.
+
+**Server Runtime configuration** can be configured in the `server/modern.server.(ts|js|mjs)` file.
+
+## Compile Configuration
+
+### Configuring in Configuration Files
+
+The configuration files for Modern.js are defined in the root directory of the project and support `.ts`, `.js`, and `.mjs` formats:
+
+- `modern.config.ts`
+- `modern.config.js`
+- `modern.config.mjs`
+
+#### modern.config.ts (Recommended)
+
+We recommend using the `.ts` format for configuration files as it provides friendly TypeScript type hints, helping you avoid errors in the configuration.
+
+Import the `defineConfig` utility function from `@modern-js/app-tools`, which will assist you with type inference and type completion for the configuration:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+});
+```
+
+#### modern.config.js
+
+If you are developing a non-TypeScript project, you can use the `.js` format for the configuration file:
+
+```js title="modern.config.js"
+export default {
+  source: {
+    alias: opts => {
+      opts['@common'] = './src/common';
+    },
+  },
+};
+```
+
+You can also configure different settings based on the environment using `process.env.NODE_ENV`:
+
+```js title="modern.config.js"
+export default {
+  server: {
+    ssr: process.env.NODE_ENV === 'development',
+  },
+};
+```
+
+#### Exporting Configuration Functions
+
+Modern.js supports exporting a function in the configuration file, where you can dynamically compute the configuration and return it to Modern.js.
+
+```js title="modern.config.js"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig(({ env, command }) => ({
+  source: {
+    alias: {
+      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
+    },
+  },
+}));
+```
+
+This function accepts the following parameters:
+
+- `env`: Corresponds to the value of `process.env.NODE_ENV`.
+  - When running `modern dev`, the value of `env` is `development`.
+  - When running `modern build` or `modern serve`, the value of `env` is `production`.
+- `command`: Corresponds to the current command being run, such as `dev`, `build`, or `serve`.
+
+#### Exporting Asynchronous Functions
+
+Modern.js also supports exporting an asynchronous function in the configuration file, allowing you to perform some asynchronous operations:
+
+```js title="modern.config.js"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig(async ({ env, command }) => {
+  const result = await someAsyncFunction();
+
+  return {
+    html: {
+      title: result,
+    },
+  };
+});
+```
+
+#### Specifying Configuration Files
+
+The Modern.js command line supports specifying the name of the configuration file using the `--config` option.
+
+For example, if you need to use the `modern.prod.config.js` file when executing the `build` command, you can add the following configuration in `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "dev": "modern dev",
+    "build": "modern build --config modern.prod.config.js"
+  }
+}
+```
+
+You can also abbreviate the `--config` option as `-c`:
+
+```bash
+$ modern build -c modern.prod.config.js
+```
+
+### Configuring in package.json (Not Recommended)
+
+In addition to configuration files, you can also set configuration items under the `modernConfig` field in `package.json`, such as:
+
+```json title="package.json"
+{
+  "modernConfig": {
+    "source": {
+      "alias": {
+        "@common": "./src/common"
+      }
+    }
+  }
+}
+```
+
+Due to the limitations of the JSON file format, only simple types such as numbers, strings, booleans, and arrays can be defined in `package.json`. When we need to set function-type values, it is recommended to do so in the Modern.js configuration file.
+
+#### Notes
+
+- It is not recommended to use both `package.json` and `modern.config.js` for configuration simultaneously. If both are used and conflicts arise, Modern.js will prompt an error in the command line.
+
+### Local Debugging Configuration
+
+To facilitate local debugging of configurations, Modern.js supports creating a `modern.config.local.(ts|js|mjs)` file in the root directory to override the configuration options in `modern.config.(ts|js|mjs)`.
+
+#### Example
+
+For example, if the `modern.config.ts` file in your project is configured with a port number of `3000`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+If you need to change the port number to `3001` for local debugging but do not want to modify the current project's `modern.config.ts` file, you can create a `modern.config.local.ts` file and add the following configuration:
+
+```ts title="modern.config.local.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3001,
+  },
+});
+```
+
+The configuration in the `modern.config.local.ts` file will be deeply merged with the configuration in `modern.config.ts`, overriding the options in `modern.config.ts`, so `server.port` will be changed to `3001`.
+
+#### Notes
+
+When using `modern.config.local.ts`, please note the following:
+
+- The `modern.config.local.ts` file will only be loaded when executing the `modern dev` commands and will not be loaded during `modern build`.
+- The priority of the `modern.config.local.ts` file is higher than both `modern.config.ts` and the `modernConfig` field in `package.json`.
+- Since `modern.config.local.ts` is only used for local debugging, it is not recommended to commit it to the code repository. Ensure that the project's `.gitignore` file includes `modern.config.local.ts` and similar files.
+
+```bash title=".gitignore"
+modern.config.local.*
+```
+
+### Merging Multiple Configurations
+
+In some cases, you may need to merge multiple configurations into one. You can use the `mergeConfig` utility function to merge multiple configurations.
+
+The `mergeConfig` function accepts an array as a parameter, where each item in the array is a configuration object. `mergeConfig` will deeply merge each configuration object in the array, automatically merging multiple function items into an array, and finally returning a merged configuration object.
+
+#### Example
+
+```ts title="modern.config.ts"
+import { mergeConfig } from '@modern-js/app-tools';
+
+const config1 = {
+  dev: {
+    port: 3000,
+  },
+  tools: {
+    postcss: () => console.log('config1');
+  },
+};
+const config2 = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: () => console.log('config2');
+  },
+};
+
+const mergedConfig = mergeConfig([config1, config2]);
+```
+
+In the above example, the merged configuration object will be:
+
+```ts
+const mergedConfig = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: [() => console.log('config1'), () => console.log('config2')],
+  },
+};
+```
+
+### Configuration Type Definitions
+
+Modern.js exports the `AppUserConfig` type, which corresponds to the type of the Modern.js configuration object:
+
+```ts title="modern.config.ts"
+import type { AppUserConfig } from '@modern-js/app-tools';
+
+const config: AppUserConfig = {
+  tools: {
+    rspack: {},
+  },
+};
+```
+
+## Runtime Configuration
+
+For detailed information on runtime configuration, please refer to the [Introduction to Runtime Configuration](/configure/app/runtime/0-intro.md).
+
+:::tip
+If the current Runtime configuration needs to be used both at compile time and runtime, please add the relevant configuration parameters at the plugin registration location.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import { xxPlugin } from '@modern-js/plugin-xx';
+
+export default defineConfig({
+  plugins: [
+    xxPlugin({
+      /** Add parameters here */
+    }),
+  ],
+});
+```
+
+:::

package/docs/guides/advanced-features/bff/cross-project.md

@@ -0,0 +1,109 @@
+# Cross-Project Invocation
+
+Based on the BFF architecture, Modern.js provides cross-project invocation capabilities, allowing BFF functions created in one project to be invoked by other projects through integrated calls, enabling function sharing and feature reuse across projects.
+Cross-project invocation consists of **producer** and **consumer** sides. The producer is responsible for creating and providing BFF services while generating integrated invocation SDK, and the consumer initiates requests through these SDK.
+
+## BFF Producer
+
+Enable cross-project invocation via configuration. Projects with BFF capabilities enabled can act as BFF producers, or you can create standalone BFF applications.
+When executing `dev` or `build`, the following artifacts for consumers will be automatically generated:
+
+- API functions under the `dist/client` directory
+- Runtime configuration functions under the `dist/runtime` directory
+- Interface exports defined in `exports` field of `package.json`
+- File list for npm publication specified in `files` field of `package.json`
+
+### Existing BFF-enabled Projects
+
+1. Enable Cross-Project Invocation
+
+Ensure the current project has BFF enabled with API files defined under `api/lambda`. Add the following configuration:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  }
+});
+```
+
+2. Generate SDK Type Files
+
+To provide type hints for the integrated invocation SDK, enable the `declaration` option in TypeScript configuration:
+
+```ts title="tsconfig.json"
+"compilerOptions": {
+    "declaration": true,
+}
+```
+
+## BFF Consumer
+
+:::info
+You can initiate requests to BFF producers from projects using any framework via the SDK.
+:::
+
+### Intra-Monorepo Invocation
+
+When producer and consumer are in the same Monorepo, directly import the SDK. API functions reside under `${package_name}/api`:
+
+```ts title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as hello } from '${package_name}/api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    hello().then(setText);
+  }, []);
+  return <div>{text}</div>;
+};
+```
+
+### Cross-Project Invocation
+
+When producer and consumer are in separate repositories, publish the BFF producer as an npm package. The invocation method remains the same as intra-Monorepo.
+
+### Domain Configuration and Extensions
+
+For real-world scenarios requiring custom BFF service domains, use the configuration function:
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+
+configure({
+  setDomain() {
+    return 'https://your-bff-api.com';
+  },
+});
+```
+
+The `configure` function from `${package_name}/runtime` supports domain configuration via `setDomain`, interceptors, and custom SDK. When extending both **current project** and **cross-project** SDK on the same page:
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+import { configure as innerConfigure } from '@modern-js/plugin-bff/client';
+import axios from 'axios';
+
+configure({
+    setDomain() {
+        return 'https://your-bff-api.com';
+    },
+});
+
+innerConfigure({
+  async request(...config: Parameters<typeof fetch>) {
+    const [url, params] = config;
+    const res = await axios({
+      url: url as string,
+      method: params?.method as Method,
+      data: params?.body,
+      headers: {
+        'x-header': 'innerConfigure',
+      },
+    });
+    return res.data;
+  },
+});
+```

package/docs/guides/advanced-features/bff/extend-server.md

@@ -0,0 +1,120 @@
+# Extend BFF Server
+
+In some applications, developers may want to handle all BFF functions uniformly, such as authentication, logging, data processing, etc.
+
+Modern.js allows users to freely extend the BFF Server through [Middleware](/guides/advanced-features/web-server.md#middleware) method.
+
+## Using Middleware
+
+:::tip Version Consistency
+Before using middleware, you need to install the `@modern-js/server-runtime` dependency. Make sure the version of `@modern-js/server-runtime` matches the version of `@modern-js/app-tools` in your project. All Modern.js official packages are released with a uniform version number, and version mismatches may cause compatibility issues.
+
+Check the version of `@modern-js/app-tools` first, then install the same version of `@modern-js/server-runtime`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/server-runtime
+pnpm add @modern-js/server-runtime@<version>
+```
+
+:::
+
+Developers can use middleware by configuring middlewares in `server/modern.server.ts`. The following describes how to write a BFF middleware manually to add permission verification:
+
+```ts title="server/modern.server.ts"
+import {
+  type MiddlewareHandler,
+  defineServerConfig,
+  getCookie,
+} from '@modern-js/server-runtime';
+
+const requireAuthForApi: MiddlewareHandler = async (c, next) => {
+  if (c.req.path.startsWith('/api') && c.req.path !== '/api/login') {
+    const sid = getCookie(c, 'sid');
+    if (!sid) {
+      return c.json({ code: -1, message: 'need login' }, 400);
+    }
+  }
+  await next();
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'require-auth-for-api',
+      handler: requireAuthForApi,
+    },
+  ],
+});
+```
+
+Then add a regular BFF function `api/lambda/hello.ts`:
+
+```ts title="api/lambda/hello.ts"
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
+
+Next, in the frontend `src/routes/page.tsx`, add the interface access code and directly use the integrated method to call:
+
+```ts title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchMyApi() {
+      const { message } = await hello();
+      setText(message);
+    }
+
+    fetchMyApi();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+Now run the `dev` command to start the project, and access `http://localhost:8080/` to find that the request for `/api/hello` has been intercepted:
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+
+Finally, modify the frontend code `src/routes/page.tsx`, and call the login interface before accessing `/api/hello`:
+
+:::note
+This part does not implement a real login interface; the code is just for demonstration.
+:::
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+import { post as login } from '@api/login';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchAfterLogin() {
+      const { code } = await login();
+      if (code === 0) {
+        const { message } = await hello();
+        setText(message);
+      }
+    }
+    fetchAfterLogin();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+Refresh the page, and you can see that the access to `/api/hello` is successful:
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
+
+The above code simulates defining middleware in `server/Modern.server.ts` and implements a simple login function. Similarly, other functionalities can be implemented in this configuration file to extend the BFF Server.