@modern-js/main-doc 2.14.0 → 2.15.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @modern-js/main-doc
 
+## 2.15.0
+
+### Patch Changes
+
+- @modern-js/builder-doc@2.15.0
+
 ## 2.14.0
 
 ### Patch Changes

package/docs/en/guides/basic-features/env-vars.mdx

@@ -31,7 +31,9 @@ MODERN_ENV priority is higher than NODE_ENV.
 
 ### MODERN_TARGET
 
-Auto inject when use `@modern-js/runtime`, Used to distinguish between SSR and CSR environments. Developers can judge by themselves in the code, and dead code will be removed by default when building.
+When using `@modern-js/runtime`, Modern.js will automatically inject `MODERN_TARGET` to distinguish between SSR and CSR environments.
+
+You can use `process.env.MODERN_TARGET` to judge the environment and execute the appropriate code.
 
 ```ts title="App.tsx"
 function App() {
@@ -41,9 +43,10 @@ function App() {
 }
 ```
 
-In the development environment, you can see that the SSR and CSR bundles as follows:
+After the development build, you can see that the SSR and CSR bundles as follows:
 
 ```js title="dist/bundles/main.js"
+// SSR bundles
 function App() {
   if (false) {
   }
@@ -51,6 +54,7 @@ function App() {
 ```
 
 ```js title="dist/static/main.js"
+// CSR bundles
 function App() {
   if (true) {
     console.log(window.innerHeight);
@@ -58,12 +62,16 @@ function App() {
 }
 ```
 
-:::note
-In a production environment, dead code is removed, such as the `if` statement above.
+This can provide different outputs for different environments to ensure that the bundle size is minimized. It can also be convenient to deal with some side effects for different environments.
 
-:::
+:::note Dead Code Elimination
+In the production environment, minimizers such as Terser and SWC will analyze the code and remove dead code to reduce the bundle size. This process is called "Dead Code Elimination" (DCE).
 
-This can provide different products for different client sides to ensure that the bundle size is minimized. It can also be convenient to deal with some side effects in the code in different environments.
+For example, the code inside the `if (false)` statement will be removed, while the code inside the `if (true)` will be preserved.
+
+If you do not use `process.env.MODERN_TARGET` as described above, the code minimizer may not be able to analyze the dead code, resulting in an increased bundle size.
+
+:::
 
 ## Custom Environment Variables
 

package/docs/en/guides/troubleshooting/dependencies.mdx

@@ -0,0 +1,110 @@
+---
+sidebar_position: 1
+---
+
+# Dependencies FAQ
+
+### How to check the actual installed version of a dependency in the project?
+
+You can use the `ls` command that provided by the package manager to view the dependencies version.
+
+The following are some basic examples, please refer to the documentation of each package manager for detailed usage.
+
+**npm / yarn**
+
+For projects using npm or yarn, the `npm ls` command can be used.
+
+For example, execute `npm ls @modern-js/core`, you can see the following results:
+
+```
+project
+└─┬ @modern-js/app-tools@2.0.0
+  └── @modern-js/core@2.0.0
+```
+
+**pnpm**
+
+For projects using pnpm, you can use `pnpm ls` command.
+
+For example, execute `pnpm ls @modern-js/core --depth Infinity`, you can see the following results:
+
+```
+devDependencies:
+@modern-js/app-tools 2.0.0
+└── @modern-js/core 2.0.0
+```
+
+---
+
+### The engine "node" is incompatible when installing dependencies?
+
+If the following error message appears when installing dependencies, it means that the version of Node.js used in the current environment is too low, and Node.js needs to be upgraded to a higher version.
+
+```bash
+The engine "node" is incompatible with this module.
+
+Expected version ">=14.17.6". Got "12.20.1"
+```
+
+When using Modern.js, it is recommended to use [Node.js 14.x](https://nodejs.org/download/release/latest-v14.x/) or [Node.js 16.x](https://nodejs.org/download/release/latest-v16.x/).
+
+If the Node.js version in the current environment is lower than the required version, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz /fnm) and other tools for version switching.
+
+Here's an example using nvm:
+
+```
+# Install Node.js v14
+nvm install 14
+
+# Switch to Node 14
+nvm use 14
+
+# Set Node 14 as the default version
+nvm default 14
+```
+
+It is recommended to use [fnm](https://github.com/Schniz/fnm) in the local development environment. Its usage is similar to nvm, but it has better performance than nvm.
+
+---
+
+### ReactNode type error after upgrading dependencies?
+
+If the following types of errors are reported after upgrading the project's dependencies, it means that the wrong `@types/react` version is installed in the project.
+
+```bash
+The types returned by 'render()' are incompatible between these types.
+Type 'React.ReactNode' is not assignable to type 'import("/node_modules/@types/react/index").ReactNode'.
+Type '{}' is not assignable to type 'ReactNode'.
+```
+
+The reason for this problem is that the ReactNode type definitions in React 18 and React 16/17 are different. If there are multiple different `@types/react` versions in the project, there will be a ReactNode type conflict, resulting in the above error.
+
+The solution is to lock `@types/react` and `@types/react-dom` in the project to a unified version, such as `v17`.
+
+```json
+{
+  "@types/react": "^17",
+  "@types/react-dom": "^17"
+}
+```
+
+For the method of locking the dependency version, please refer to [Lock nested dependency](/guides/get-started/upgrade.html#lock-nested-dependency).
+
+---
+
+### After pnpm install, there are some peer dependencies warnings in the console?
+
+The reason for this warning is that the version range of peer dependencies declared by some third-party npm packages does not match the version range installed in Modern.js.
+
+In most cases, you can ignore the peer dependency warnings because it will not affect the use of Modern.js.
+
+---
+
+### What is the minimum React version supported by the Modern.js framework?
+
+The recommended React version for **Modern.js framework is >= 18.0.0**, and different features have different React version requirements.
+
+- If you are using React 17, some framework features, such as Steaming SSR, will not be available as they rely on new features provided by React 18.
+- If you're still using React 16, you won't be able to use Modern.js's runtime or server-side featurs. You can consider using Modern.js's build mode, that is, only use Modern.js as a builder. In this case, you can still use React 16.
+
+In a future major release of Modern.js, we will remove support for React 16 and React 17. Please upgrade to React 18+ as soon as possible.

package/docs/zh/guides/basic-features/env-vars.mdx

@@ -31,7 +31,9 @@ MODERN_ENV 的优先级高于 NODE_ENV。
 
 ### MODERN_TARGET
 
-使用 `@modern-js/runtime` 时会自动注入，用于区分 SSR 与 CSR 环境。开发者可以自行在代码中判断，构建时会默认移除 dead code。
+使用 `@modern-js/runtime` 时，Modern.js 会自动注入 `MODERN_TARGET`，用于区分 SSR 与 CSR 环境。
+
+你可以在代码中通过 `process.env.MODERN_TARGET` 来判断环境，并执行相应的逻辑。
 
 ```ts title="App.tsx"
 function App() {
@@ -41,9 +43,10 @@ function App() {
 }
 ```
 
-开发环境打包后，可以看到 SSR 产物和 CSR 产物如下：
+在开发环境构建完成后，可以看到 SSR 产物和 CSR 产物如下：
 
 ```js title="dist/bundles/main.js"
+// SSR 产物
 function App() {
   if (false) {
   }
@@ -51,6 +54,7 @@ function App() {
 ```
 
 ```js title="dist/static/main.js"
+// CSR 产物
 function App() {
   if (true) {
     console.log(window.innerHeight);
@@ -58,12 +62,17 @@ function App() {
 }
 ```
 
-:::note
-在生产环境，会将 dead code 移除，例如上述 `if` 语句。
+这种方式可以针对不同客户端提供不同的产物，保证代码体积最小化；也便于处理不同环境下代码中的一些副作用。
+
+:::note 死代码移除
+在生产环境，Terser 和 SWC 等代码压缩工具会分析代码，并将 dead code 移除，从而减少产物体积，这个过程被称为死代码移除（DCE）。
+
+例如，上述 `if (false)` 语句包含的代码会被移除，而 `if (true)` 包含的代码将被保留。
+
+如果你未按照上述写法来使用 `process.env.MODERN_TARGET`，代码压缩工具可能会无法分析出 dead code，从而导致产物体积增大。
 
 :::
 
-这种方式可以针对不同客户端提供不同的产物，保证代码体积最小化。也能方便处理不同环境下，代码中的一些副作用，
 
 ## 自定义环境变量
 

package/docs/zh/guides/troubleshooting/dependencies.mdx

@@ -18,8 +18,8 @@ sidebar_position: 1
 
 ```
 project
-└─┬ @modern-js/app-tools@1.6.10
-  └── @modern-js/core@1.12.4
+└─┬ @modern-js/app-tools@2.0.0
+  └── @modern-js/core@2.0.0
 ```
 
 **pnpm**
@@ -30,8 +30,8 @@ project
 
 ```
 devDependencies:
-@modern-js/app-tools 1.7.0
-└── @modern-js/core 1.13.0
+@modern-js/app-tools 2.0.0
+└── @modern-js/core 2.0.0
 ```
 
 ---
@@ -88,7 +88,7 @@ Type '{}' is not assignable to type 'ReactNode'.
 }
 ```
 
-关于锁定依赖版本的方法，请参考上方的 `如何锁定项目中的某个依赖版本？`。
+关于锁定依赖版本的方法，请参考 [锁定子依赖](/guides/get-started/upgrade.html#锁定子依赖)。
 
 ---
 
@@ -97,3 +97,14 @@ Type '{}' is not assignable to type 'ReactNode'.
 出现该警告的原因是，某些三方 npm 包声明的 peer dependencies 版本范围与 Modern.js 中安装的版本范围不一致。
 
 绝大多数情况下，peer dependencies 的警告不会影响项目运行，不需要额外进行处理，请忽略相关 warning。
+
+---
+
+### Modern.js 框架最低支持的 React 版本是多少？
+
+**Modern.js 框架推荐使用的 React 版本为 >= 18.0.0**，并且不同功能对 React 版本的要求有所不同。
+
+- 如果你在使用 React 17，那么部分框架功能将无法使用，比如 Steaming SSR，因为它依赖 React 18 提供的新特性。
+- 如果你仍然在使用 React 16，那么将无法使用 Modern.js 的运行时或服务端能力。你可以考虑使用 Modern.js 的构建模式，即只使用 Modern.js 的构建能力，这种情况是可以继续使用 React 16 的。
+
+在 Modern.js 未来的 major 版本中，我们会逐步移除对 React 16 和 React 17 的支持。因此，请尽快升级到 React 18 以上版本。

package/package.json

@@ -11,13 +11,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.14.0",
+  "version": "2.15.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.14.0"
+    "@modern-js/builder-doc": "^2.15.0"
   },
   "devDependencies": {
     "classnames": "^2",
@@ -29,9 +29,9 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.14.0",
-    "@modern-js/doc-tools": "2.14.0",
-    "@modern-js/doc-plugin-auto-sidebar": "2.14.0"
+    "@modern-js/builder-doc": "2.15.0",
+    "@modern-js/doc-tools": "2.15.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.15.0"
   },
   "scripts": {
     "dev": "modern dev",