@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,57 @@
+---
+title: minifyCss
+---
+
+# tools.minifyCss
+
+- **Type:** `Object | Function | undefined`
+- **Default:**
+
+```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

@@ -0,0 +1,38 @@
+---
+title: postcss
+---
+
+# tools.postcss
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultOptions = {
+  postcssOptions: {
+    plugins: [
+      // The following plugins are enabled by default
+      require('postcss-nesting'),
+      require('postcss-media-minmax'),
+      require('postcss-flexbugs-fixes'),
+      require('autoprefixer')({
+        flexbox: 'no-2009',
+      }),
+      // The following plugins are only enabled when compatible with legacy browsers
+      require('postcss-custom-properties'),
+      require('postcss-initial'),
+      require('postcss-page-break'),
+      require('postcss-font-variant'),
+    ],
+    sourceMap: isDev,
+  },
+};
+```
+
+Modern.js integrates PostCSS by default, you can configure [postcss-loader](https://github.com/webpack-contrib/postcss-loader) through `tools.postcss`.
+
+It should be noted that when you enable the `tools.lightningcss` configuration, PostCSS will be disabled by default, including `postcss-loader` and its default plugins.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.postcss" />

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

@@ -0,0 +1,14 @@
+---
+title: rspack
+---
+
+# tools.rspack
+
+- **Type:** `Rspack.Configuration | Function | undefined`
+- **Default:** `undefined`
+
+`tools.rspack` is used to configure [Rspack](https://rspack.rs/).
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.rspack" />

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

@@ -0,0 +1,82 @@
+---
+title: sass
+---
+
+# tools.sass
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultOptions = {
+  // CSS Source Map enabled by default in development environment
+  sourceMap: isDev,
+};
+```
+
+You can modify the config of [sass-loader](https://github.com/webpack-contrib/sass-loader) via `tools.sass`.
+
+### Object Type
+
+When `tools.sass` is `Object` type, it is merged with the default config through Object.assign. It should be noted that `sassOptions` is merged through deepMerge in a deep way.
+
+For example:
+
+```js
+export default {
+  tools: {
+    sass: {
+      sourceMap: true,
+    },
+  },
+};
+```
+
+### Function Type
+
+When `tools.sass` 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: {
+    sass(config) {
+      // Modify sourceMap config
+      config.additionalData = async (content, loaderContext) => {
+        // ...
+      };
+    },
+  },
+};
+```
+
+### Modifying Sass Version
+
+In some scenarios, if you need to use a specific version of Sass instead of the built-in Dart Sass v1 in Modern.js, you can install the desired Sass version in your project and set it up using the `implementation` option of the `sass-loader`.
+
+```js
+export default {
+  tools: {
+    sass: {
+      implementation: require('sass'),
+    },
+  },
+};
+```
+
+### Utility Function
+
+#### addExcludes
+
+- **Type:** `(excludes: RegExp | RegExp[]) => void`
+
+Used to specify which files `sass-loader` does not compile, You can pass in one or more regular expressions to match the path of sass files, for example:
+
+```js
+export default {
+  tools: {
+    sass(config, { addExcludes }) {
+      addExcludes(/node_modules/);
+    },
+  },
+};
+```

package/docs/en/configure/app/tools/style-loader.mdx

@@ -0,0 +1,14 @@
+---
+title: styleLoader
+---
+
+# tools.styleLoader
+
+- **Type:** `Object | Function`
+- **Default:** `{}`
+
+The config of [style-loader](https://github.com/webpack-contrib/style-loader) can be set through `tools.styleLoader`.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="tools.styleLoader" />

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

@@ -0,0 +1,69 @@
+---
+title: swc
+---
+
+# tools.swc
+
+- **Type:** `Object | Function`
+- **Default:** `undefined`
+
+## Introduction
+
+import SWC from '@site-docs-en/components/swc.mdx';
+
+<SWC />
+
+:::tip
+When using Rspack as the bundler, SWC will be used for transpiling and compression by default, so you don't need to install or configure the SWC plugin.
+:::
+
+## Used in Rspack mode
+
+You can set the options of [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader) through `tools.swc`.
+
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    swc: {
+      jsc: {
+        externalHelpers: false,
+      },
+    },
+  },
+});
+```
+
+For more usage, please refer to [Rsbuild - tools.swc](https://v2.rsbuild.rs/config/tools/swc).
+
+### Register SWC Plugin
+
+Modern.js supports registering SWC's Wasm plugin through `tools.swc`, such as registering [@swc/plugin-styled-components](https://www.npmjs.com/package/@swc/plugin-styled-components):
+
+```ts
+export default {
+  tools: {
+    swc: {
+      jsc: {
+        experimental: {
+          plugins: [['@swc/plugin-styled-components', {}]],
+        },
+      },
+    },
+  },
+};
+```
+
+Please note that the SWC plugin is still an experimental feature, and the SWC Wasm plugin is currently not backward compatible. The version of the SWC plugin is closely tied to the version of swc_core that Rspack depends on.
+
+This means that you must to choose an SWC plugin that matches the current version of swc_core to ensure that it works properly. If the version of the SWC plugin you are using does not match the version of swc_core that Rspack depends on, Rspack will throw the following error during the build process:
+
+```
+1: failed to run Wasm plugin transform. Please ensure the version of `swc_core`
+   used by the plugin is compatible with the host runtime.
+```
+
+If you encounter the above issues, a common solution is to upgrade both the Modern.js and SWC plugins to the latest versions.
+
+For details, please refer to [Rsbuild - SWC Plugin Version](https://v2.rsbuild.rs/guide/configuration/swc#swc-plugin-version).

package/docs/en/configure/app/tools/ts-checker.mdx

@@ -0,0 +1,56 @@
+---
+title: tsChecker
+---
+
+# tools.tsChecker
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultOptions = {
+  typescript: {
+    // avoid OOM issue
+    memoryLimit: 8192,
+    // use tsconfig of user project
+    configFile: tsconfigPath,
+    // use TS-Go native preview of user project
+    typescriptPath: require.resolve('@typescript/native-preview/package.json'),
+  },
+  issue: {
+    exclude: [
+      { file: '**/*.(spec|test).ts' },
+      { file: '**/node_modules/**/*' },
+    ],
+  },
+  logger: {
+    log() {
+      // do nothing
+      // we only want to display error messages
+    },
+    error(message: string) {
+      console.error(message.replace(/ERROR/g, 'Type Error'));
+    },
+  },
+},
+```
+
+By default, Modern.js type checking is aligned with the TS-Go native preview used by this fork. You can use `output.disableTsChecker` config to disable build-time checking.
+
+## Example
+
+When the value of `tsChecker` is of type Object, it will be deeply merged with the default configuration.
+
+```ts
+export default {
+  tools: {
+    tsChecker: {
+      issue: {
+        exclude: [({ file = '' }) => /[\\/]some-folder[\\/]/.test(file)],
+      },
+    },
+  },
+};
+```
+
+> This fork keeps the TypeScript toolchain on `@typescript/native-preview` / `tsgo`; do not install the classic `typescript` compiler for application type checking.

package/docs/en/configure/app/usage.mdx

@@ -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.html).
+
+:::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/en/guides/_meta.json

@@ -0,0 +1,37 @@
+[
+  {
+    "type": "dir",
+    "name": "get-started",
+    "label": "gettingStarted"
+  },
+  {
+    "type": "dir",
+    "name": "concept",
+    "label": "concept"
+  },
+  {
+    "type": "dir",
+    "name": "basic-features",
+    "label": "basic"
+  },
+  {
+    "type": "dir",
+    "name": "advanced-features",
+    "label": "advanced"
+  },
+  {
+    "type": "dir",
+    "name": "topic-detail",
+    "label": "topic"
+  },
+  {
+    "type": "dir",
+    "name": "troubleshooting",
+    "label": "troubleshooting"
+  },
+  {
+    "type": "dir",
+    "name": "upgrade",
+    "label": "Upgrade"
+  }
+]

package/docs/en/guides/advanced-features/_meta.json

@@ -0,0 +1,32 @@
+[
+  {
+    "type": "dir",
+    "name": "bff",
+    "label": "use-bff",
+    "collapsed": true
+  },
+
+  {
+    "type": "dir",
+    "name": "page-performance",
+    "label": "page-performance",
+    "collapsed": true
+  },
+  "build-performance",
+  "compatibility",
+  "low-level",
+  "source-build",
+  {
+    "type": "dir",
+    "name": "server-monitor",
+    "label": "server-monitor",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "international",
+    "label": "Internationalization",
+    "collapsed": true
+  },
+  "web-server"
+]

package/docs/en/guides/advanced-features/bff/_meta.json

@@ -0,0 +1,10 @@
+[
+  "function",
+  "frameworks",
+  "data-platform",
+  "operators",
+  "extend-server",
+  "sdk",
+  "upload",
+  "cross-project"
+]