@modern-js/main-doc 2.19.2-alpha.0 → 2.21.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @modern-js/main-doc
 
+## 2.21.0
+
+### Patch Changes
+
+- 26dcf3a: chore: bump typescript to v5 in devDependencies
+
+  chore: 升级 devDependencies 中的 typescript 版本到 v5
+
+- Updated dependencies [1ef03dc]
+  - @modern-js/builder-doc@2.21.0
+
+## 2.20.0
+
+### Patch Changes
+
+- 3c4e0a5: chore(utils): move generateMetaTags method to builder-shared
+
+  chore(utils): 移动 generateMetaTags 方法到 builder-shared
+
+- 0ce52ad: docs(main): optimize mobile adaptation
+
+  docs(main): 优化移动端适配
+
+  - @modern-js/builder-doc@2.20.0
+
 ## 2.19.1
 
 ### Patch Changes

package/docs/en/apis/app/runtime/router/router.mdx

@@ -107,6 +107,28 @@ function App() {
 }
 ```
 
+### useRouteError
+
+```ts
+export declare function useRouteError(): unknown;
+```
+
+`useRouteError` returns the nearest ancestor Route error。
+
+```tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError();
+  return (
+    <div>
+      <h1>{error.status}</h1>
+      <h2>{error.message}</h2>
+    </div>
+  );
+};
+export default ErrorBoundary;
+```
+
 ## Components
 
 ### Link

package/docs/en/components/init-rspack-app.mdx

@@ -1,5 +1,5 @@
 ```bash
-$ npx @modern-js/create myapp
+$ npx @modern-js/create@latest myapp
 ? Please select the solution you want to create: Web App
 ? Development Language: TS
 ? Package Manager: pnpm

package/docs/en/components/ua-polyfill.mdx

@@ -0,0 +1,40 @@
+
+### Polyfill At Runtime
+
+Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information, which has the following advantages over Babel:
+
+- It will not be inserted into the code, reducing the code .
+- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster.
+
+exec `pnpm run new` to enable this features:
+
+```bash
+? Action Enable features
+? Enable features Enable UA-based Polyfill Feature
+```
+
+After executing the command, register the Polyfill plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import polyfillPlugin from '@modern-js/plugin-polyfill';
+
+export default defineConfig({
+  plugins: [..., polyfillPlugin()],
+});
+```
+
+After configuring `output.polyfill` as `ua` and executing `pnpm run build & & pnpm run serve` to start the server, visiting the page can see that the HTML product contains the following script:
+
+```js
+<script src="/__polyfill__" crossorigin></script>
+```
+
+Visit the page `http://localhost:8080/__polyfill__` on Chrome 51 to see:
+
+![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
+
+:::caution
+This feature only works when using Modern.js built-in Web Server.
+
+If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through html.template / tools.html will cause this feature not work.
+:::

package/docs/en/configure/app/output/temp-dir.mdx

@@ -0,0 +1,24 @@
+---
+sidebar_label: tempDir
+---
+
+# output.tempDir
+
+- **Type:** `string`
+- **Default:** `''`
+
+When developing or building a project, Modern.js generates real Webpack entries and HTML templates, placing them in a temporary directory.
+
+If you want to start a project with multiple configurations at the same time, you can use this configuration to generate files in different temporary directories to avoid interference with each other.
+
+The configuration can be a relative or absolute path, but paths outside the project should be avoided.
+
+Example:
+
+```ts
+export default {
+  output: {
+    tempDir: path.join('node_modules', '.temp-dir'),
+  }
+}
+```

package/docs/en/configure/app/security/nonce.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: nonce
+---
+
+# security.nonce
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [security.nonce](https://modernjs.dev/builder/en/api/config-security.html#securitynonce).
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/security/nonce.md';
+
+<Main />

package/docs/en/guides/advanced-features/compatibility.mdx

@@ -1,8 +1,26 @@
 ---
-title: Compatibility
 sidebar_position: 5
 ---
-# Compatibility
+
+# Browser Compatibility
+
+## Browserslist Configuration
+
+Modern.js supports setting the browserslist for your web applications. You can set the [Browserslist](https://browsersl.ist/) in the `.browserslistrc` file.
+
+When you create a new Modern.js project, it includes a `.browserslistrc` configuration by default, which means that JavaScript code will be compiled to ES6.
+
+```yaml title=".browserslistrc"
+chrome >= 51
+edge >= 15
+firefox >= 54
+safari >= 10
+ios_saf >= 10
+```
+
+:::tip
+Please refer to [Modern.js Builder - Browserslist](https://modernjs.dev/builder/en/guide/advanced/browserslist) for more information.
+:::
 
 ## Browserslist
 
@@ -38,42 +56,6 @@ For case where Polyfill is not required for third-party dependencies, you can se
 
 :::
 
-### Polyfill At Runtime
-
-Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information, which has the following advantages over Babel:
-
-- It will not be inserted into the code, reducing the code .
-- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster.
-
-exec `pnpm run new` to enable this features:
-
-```bash
-? Action Enable features
-? Enable features Enable UA-based Polyfill Feature
-```
+import UAPolyfill from '@site-docs-en/components/ua-polyfill';
 
-After executing the command, register the Polyfill plugin in `modern.config.ts`:
-
-```ts title="modern.config.ts"
-import polyfillPlugin from '@modern-js/plugin-polyfill';
-
-export default defineConfig({
-  plugins: [..., polyfillPlugin()],
-});
-```
-
-After configuring `output.polyfill` as `ua` and executing `pnpm run build & & pnpm run serve` to start the server, visiting the page can see that the HTML product contains the following script:
-
-```js
-<script src="/__polyfill__" crossorigin></script>
-```
-
-Visit the page `http://localhost:8080/__polyfill__` on Chrome 51 to see:
-
-![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
-
-:::caution
-This feature only works when using Modern.js built-in Web Server.
-
-If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through html.template / tools.html will cause this feature not work.
-:::
+<UAPolyfill />

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -57,3 +57,41 @@ import appTools, { defineConfig } from '@modern-js/app-tools';
 :::tip
 When migrating from webpack to Rspack, there may have some differences in build and configuration capabilities. For more details, please refer to [Configuration Differences](https://modernjs.dev/builder/en/guide/advanced/rspack-start.html#migrating-from-webpack-to-rspack).
 :::
+
+## The relationship between Rspack and Modern.js versions
+
+Usually, the latest version of Rspack will be integrated into Modern.js. You can update the Modern.js-related dependencies and built-in Rspack to the latest version by using `npx modern upgrade` in your project.
+
+However, Modern.js uses a locked version dependency method (non-automatic upgrade) for Rspack. Due to differences in release cycles, the version of Rspack integrated into Modern.js may be behind the latest version of Rspack.
+
+When Rspack is enabled for building through dev / build, the current version of Rspack used in the framework will be printed automatically:
+
+![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/img_v2_dfcf051f-21db-4741-a108-d9f7a82c3abg.png)
+
+### Override the Built-in Rspack Version
+
+You can override Rspack to a specific version using the capbilities provided by package managers such as pnpm, yarn, npm.
+
+For example, if you are using pnpm, you can update the Rspack version with `overrides` as shown below:
+
+```json title=package.json
+{
+  "pnpm": {
+    "overrides": {
+      "@rspack/core": "nightly",
+      "@rspack/dev-client": "nightly",
+      "@rspack/dev-middleware": "nightly",
+      "@rspack/plugin-html": "nightly",
+      "@rspack/postcss-loader": "nightly"
+    }
+  }
+}
+```
+
+:::tip What is Rspack Nightly Version
+The Rspack nightly build fully replicates the full release build for catching errors early.
+Usually it is available and any errors that arise will fixed promptly.
+However, if there are any break changes that require modern.js to modify the code, we recommend to wait for the next version of modern.js.
+:::
+
+More examples of using package management tools, please refer to: [Lock nested dependency](/guides/get-started/upgrade.html#lock-nested-dependency).

package/docs/en/guides/basic-features/css.mdx

@@ -4,33 +4,33 @@ sidebar_position: 2
 
 # CSS Solutions
 
-Modern.js has built-in multiple CSS solutions, including Less / Sass / Stylus preprocessor, PostCSS, CSS Modules, CSS-in-JS and Tailwind CSS.
+Modern.js has built-in a variety of commonly used CSS solutions, including Less / Sass / Stylus preprocessors, PostCSS, CSS Modules, CSS-in-JS, and Tailwind CSS.
 
 ## Using Less, Sass and Stylus
 
-Modern.js has built-in community popular CSS preprocessors such as Less, Sass.
+Modern.js has built-in popular community CSS preprocessors, including Less and Sass.
 
-By default, you don't need to configure anything for Less and Sass. If you need to customize loader config, you can configure [tools.less](/configure/app/tools/less), [tools.sass](/configure/app/tools/sass) to set it up.
+By default, you don't need to configure Less and Sass. If you have custom loader configuration requirements, you can set them up by configuring [tools.less](/configure/app/tools/less) and [tools.sass](/configure/app/tools/sass).
 
-You can also use Stylus in Modern.js, just install the Stylus plugin provided by Modern.js Builder, please refer to [Stylus Plugin](https://modernjs.dev/builder/en/plugins/plugin-stylus.html) for usage.
+You can also use Stylus in Modern.js by installing the Stylus plugin provided by Modern.js Builder. For usage, please refer to [Stylus Plugin](https://modernjs.dev/builder/plugins/plugin-stylus.html).
 
 ## Using PostCSS
 
-Modern.js has built-in [PostCSS](https://postcss.org/) to transform the CSS code.
+Modern.js has built-in [PostCSS](https://postcss.org/) to transform CSS code.
 
 Please refer to [Modern.js Builder - Using PostCSS](https://modernjs.dev/builder/en/guide/basic/css-usage.html#using-postcss) for detailed usage.
 
 ## Using CSS Modules
 
-Please read the [Using CSS Modules](https://modernjs.dev/builder/en/guide/basic/css-modules.html) chapter for a complete usage of CSS Modules.
+Please read the [Using CSS Modules](https://modernjs.dev/builder/en/guide/basic/css-modules.html) section to learn about the complete usage of CSS Modules.
 
 ## Using CSS-in-JS
 
-CSS-in-JS is a technology that can write CSS styles in JS files.
+CSS-in-JS is a technique that allows you to write CSS styles in JS files.
 
-Modern.js integrates the CSS-in-JS library [styled-components](https://styled-components.com/) commonly used in the community, which uses the new feature of JavaScript [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write CSS styles for components. You can use the [styled-components](https://styled-components.com/) API directly from `@modern-js/runtime/styled`.
+Modern.js integrates the popular CSS-in-JS implementation library [styled-components](https://styled-components.com/), which uses the new JavaScript feature [Tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates) to write component CSS styles. You can directly import the API of [styled-components](https://styled-components.com/) from `@modern-js/runtime/styled` for use.
 
-When you need to write a `div` component with an internal font in red, you can do the following implementation:
+When you need to write a `div` component with an internal font color of red, you can implement it as follows:
 
 ```js
 import styled from '@modern-js/runtime/styled';
@@ -40,7 +40,7 @@ const RedDiv = styled.div`
 `;
 ```
 
-When you need to dynamically set the component style according to the `props` of the component, for example, when the attribute `primary` of `props` is `true`, the color of the button is white, and otherwise it is red. The implementation code is as follows:
+If you need to dynamically set component styles based on the component's `props`, for example, the `primary` property of `props` is `true`, the button color is white, otherwise it is red, you can implement the code as follows:
 
 ```js
 import styled from '@modern-js/runtime/styled';
@@ -51,26 +51,36 @@ const Button = styled.button`
 `;
 ```
 
-For more usage of styled-components, please refer to [[styled-components official website](https://styled-components.com/) ].
+For more usage of styled-components, please refer to [styled-components official website](https://styled-components.com/).
 
-Modern.js uses the Babel plugin [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) internally, and the plugin can be configured through [tools.styledComponents](/configure/app/tools/styled-components).
+Modern.js integrates Babel's [babel-plugin-styled-components](https://github.com/styled-components/babel-plugin-styled-components) plugin internally, and you can configure the plugin through [tools.styledComponents](/configure/app/tools/styled-components).
 
 :::tip
-If you need to use [styled-jsx](https://www.npmjs.com/package/styled-jsx), [Emotion](https://emotion.sh/) and other CSS-in-JS libraries, you need to install the dependency of the corresponding library first. For specific usage, please refer to the official website of the corresponding library.
+If you need to use other CSS-in-JS libraries such as [styled-jsx](https://www.npmjs.com/package/styled-jsx) and [Emotion](https://emotion.sh/), you need to install the corresponding dependencies first. For specific usage, please refer to the library's official website.
 :::
 
 ## Using Tailwind CSS
 
-[Tailwind CSS](https://tailwindcss.com/) is a CSS framework and design system based on Utility Class, which can quickly add common styles to components, and support flexible extension of theme styles. To use [Tailwind CSS](https://tailwindcss.com/) in the Modern.js, just execute `pnpm run new` in the project root directory and turn it on.
+[Tailwind CSS](https://tailwindcss.com/) is a CSS framework and design system based on Utility Class, which can quickly add common styles to components, and support flexible extension of theme styles. To use [Tailwind CSS](https://tailwindcss.com/) in Modern.js, simply run `pnpm run new` in the project root directory and enable it.
 
-Choose as follows:
+Follow the steps below to make a selection:
 
 ```bash
 ? Action: Enable features
 ? Enable features: Enable Tailwind CSS
 ```
 
-When using, add the following code to the root component of the entry (such as `src/App.jsx`):
+Register the Tailwind plugin in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
+
+export default defineConfig({
+  plugins: [..., tailwindcssPlugin()],
+});
+```
+
+To use, add the following code to the root component (such as `src/App.jsx`) of the entry:
 
 ```js
 import 'tailwindcss/base.css';
@@ -78,7 +88,7 @@ import 'tailwindcss/components.css';
 import 'tailwindcss/utilities.css';
 ```
 
-You can then use the Utility Class provided by Tailwind CSS in each component:
+Then you can use the Utility Class provided by Tailwind CSS in each component:
 
 ```tsx
 const App = () => (
@@ -88,14 +98,14 @@ const App = () => (
 );
 ```
 
-:::info Additional
-According to different needs, you can optionally import the CSS files provided by Tailwind CSS. Since the use of `@taiwind` is equivalent to directly importing CSS files, you can refer to the content in the annotate in the [`@tailwind` usage](https://tailwindcss.com/docs/functions-and-directives#tailwind) document for the purpose of the CSS files provided by Tailwind CSS.
+:::info Additional Information
+Depending on your needs, you can selectively import the CSS files provided by Tailwind CSS. Since using `@tailwind` is equivalent to directly importing CSS files, you can refer to the comments in the [`@tailwind` usage](https://tailwindcss.com/docs/functions-and-directives#tailwind) documentation for the purpose of the CSS files provided by Tailwind CSS.
 
 :::
 
-### Tailwind CSS version
+### Tailwind CSS Version
 
-Modern.js supports both Tailwind CSS v2 and v3. The framework will recognize the version of `tailwindcss` in the project `package.json` and apply the corresponding configuration. By default, we install Tailwind CSS v3 for you.
+Modern.js supports both Tailwind CSS v2 and v3 versions, and the framework will recognize the version of the `tailwindcss` dependency in the project `package.json` file and enable the corresponding configuration. By default, we will install Tailwind CSS v3 version for you.
 
 If your project is still using Tailwind CSS v2, we recommend that you upgrade to v3 to support JIT and other capabilities. For the differences between Tailwind CSS v2 and v3 versions, please refer to the following articles:
 
@@ -104,16 +114,16 @@ If your project is still using Tailwind CSS v2, we recommend that you upgrade to
 
 ### Browser Compatibility
 
-Both Tailwind CSS v2 and v3 do not support IE 11 browsers. For background, please refer to:
+Tailwind CSS v2 and v3 do not support the IE 11 browser, please refer to:
 
 - [Tailwind CSS v3 - Browser Support](https://tailwindcss.com/docs/browser-support).
 - [Tailwind CSS v2 - Browser Support](https://v2.tailwindcss.com/docs/browser-support)
 
-If you use Tailwind CSS on IE 11 browser, some styles may not be available, please pay attention.
+If you use Tailwind CSS on IE 11 browser, some styles may not be available, please use it with caution.
 
-### Theme config
+### Theme Configuration
 
-When you need to customize the [theme](https://tailwindcss.com/docs/theme) configuration of Tailwind CSS, you can modify it in the configuration [`source.designSystem`](/configure/app/source/design-system), for example, add a color theme `primary`:
+When you need to customize the [theme](https://tailwindcss.com/docs/theme) configuration of Tailwind CSS, you can modify it in the [`source.designSystem`](/configure/app/source/design-system) configuration. For example, adding a `primary` color theme:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -129,7 +139,7 @@ export default defineConfig({
 });
 ```
 
-When you need special configuration for Tailwind CSS other than [theme](https://tailwindcss.com/docs/theme), you can configure it in [`tools.tailwindcss`](/configure/app/tools/tailwindcss), for example setting `variants`:
+When you need to make other special configurations to Tailwind CSS besides [theme](https://tailwindcss.com/docs/theme), you can configure them in [`tools.tailwindcss`](/configure/app/tools/tailwindcss), such as setting `variants`:
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -145,4 +155,4 @@ export default defineConfig({
 });
 ```
 
-> When configuring Tailwind CSS for a project, the combination of the two configurations [source.designSystem](/configure/app/source/design-system) and [tools.tailwindcss](/configure/app/tools/tailwindcss) is equivalent to a separate configuration `tailwindcss.config.js` file. Where [source.designSystem](/configure/app/source/design-system) is equivalent to the [theme](https://v2.tailwindcss.com/docs/configuration#theme) configuration of Tailwind CSS.
+> When you configure Tailwind CSS for your project, the combination of [source.designSystem](/configure/app/source/design-system) and [tools.tailwindcss](/configure/app/tools/tailwindcss) configurations is equivalent to configuring a `tailwindcss.config.js` file separately. [source.designSystem](/configure/app/source/design-system) is equivalent to the Tailwind CSS [theme](https://v2.tailwindcss.com/docs/configuration#theme) configuration.