@modern-js/module-tools-docs 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @modern-js/module-tools-docs
 
+## 2.9.0
+
+### Patch Changes
+
+- 540205e909: docs(module-tools-doc): format content
+  docs(module-tools-doc): 格式化内容
+  - @modern-js/doc-tools@2.9.0
+  - @modern-js/doc-plugin-auto-sidebar@2.9.0
+
 ## 2.8.0
 
 ### Patch Changes

package/docs/en/guide/advance/asset.mdx

@@ -32,10 +32,6 @@ import img from './bg.png';
 
 Project source code.
 
-```ts ./src/asset.ts
-import img from './bg.png';
-//...
-```
 
 ---
 
@@ -71,8 +67,8 @@ If the size of `bg.png` is larger than 10 kb, then the product directory structu
 ---
 
 ```js ./dist/asset.js
-var bg_default = 'assets/bg.13e2aba2.png';
-console.info(bg_default);
+import img from './assets/bg.13e2aba2.png';
+console.info(img);
 ```
 
 </CH.Code>
@@ -84,62 +80,3 @@ When wanting to modify the default behavior, the following API can be used:
 - `asset.path`: modify the output path of the static resource file.
 - `asset.limit`: modify the threshold value for inline static resource files.
 
-## Setting CDN Prefix
-
-If the project is running in a browser environment, we may need to host static resources to a CDN and then use them in the production environment.
-
-Then we need to add the CDN base path in front of the path to the static resource file in the default generated build product. Again, see an example:
-
-<CH.Spotlight>
-
-```ts ./src/asset.ts
-import img from './bg.png';
-//...
-```
-
----
-
-Project source code.
-
-```ts ./src/asset.ts
-
-```
-
----
-
-`modern.config` config file。
-
-```ts ./modern.config.ts
-export default defineConfig({
-  buildConfig: {
-    format: 'umd',
-    asset: {
-      publicPath: 'https://cdn/',
-    },
-  },
-});
-```
-
----
-
-If the size of `bg.png` is larger than 10 kb, then the product content will be.
-
-```js ./dist/asset.js focus=7:7
-(function (global, factory) {
-  if (typeof module === 'object' && typeof module.exports === 'object')
-    factory();
-  else if (typeof define === 'function' && define.amd) define([], factory);
-  else if (
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self)
-  )
-    factory();
-})(this, function () {
-  'use strict';
-  var bg_default = 'http://cdn/assets/bg.13e2aba2.png';
-  // src/asset.tsx
-  console.info(bg_default);
-});
-```
-
-</CH.Spotlight>
-

package/docs/en/guide/advance/external-dependency.mdx

@@ -19,7 +19,11 @@ In addition to `"dependencies"`, [`"peerDependencies"`](/en/guide/basic/before-g
 
 ## Default handling of third-party dependencies
 
-By default, third-party dependencies under `"dependencies"` and `"peerDependencies"` are not packaged in the module project\*\*, so:
+In module projects, **by default, third-party dependencies under `"dependencies"` and `"peerDependencies"` are not packaged**. This is because when the npm package is released, the `"dependencies"` for the npm package will be installed when the npm package is installed.
+
+- By not packaging `"dependencies"`, you can reduce the size of the package product.
+- If you need to package, move `"dependencies"` to `"peerDependencies"`, which is equivalent to a **prebundle** of dependencies to reduce the size of the dependency installation.
+
 
 <CH.Spotlight>
 

package/docs/en/guide/advance/in-depth-about-build.md

@@ -25,15 +25,19 @@ A Bundle is a package of build products, which may be a single file or multiple
 
 Bundleless, on the other hand, means that each source file is compiled and built separately, but not packaged together. Each product file can be found with its corresponding source code file. The process of **Bundleless build can also be understood as the process of code conversion of source files only**.
 
+They have their own benefits.
+
+- Bundle can reduce the size of build products and also pre-package dependencies to reduce the size of installed dependencies. Packaging libraries in advance can speed up application project builds.
+- Bundleless maintains the original file structure and is more conducive to debugging and tree shaking.
+
 In `buildConfig` you can specify whether the current build task is Bundle or Bundleless by using [`buildConfig.buildType`](/en/api/config/build-config#buildtype).
 
 ### Relationship between `input` and `sourceDir`
 
 [`buildConfig.input`](/en/api/config/build-config#input) is used to specify the file path or directory path where the source code is read, and its default value differs between Bundle and Bundleless builds.
 
-- When `buildType: 'bundle'`, `input` defaults to `['src/index.ts']`
+- When `buildType: 'bundle'`, `input` defaults to `src/index.(j|t)sx?`
 - When `buildType: 'bundleless'`, `input` defaults to `['src']`
-  > In fact, at `buildType: 'bundle'`, the build tool detects the existence of a file matching the name rule `src/index.(j|t)sx?` and uses it as an entry file.
 
 :::warning{title=notes}
 It is recommended that you do not specify multiple source file directories during a Bundleless build, as unintended results may occur. Bundleless builds with multiple source directories are currently in an unstable stage.

package/docs/en/guide/best-practices/components.mdx

@@ -9,10 +9,10 @@ This chapter will describe how to develop component projects using the module en
 ```bash Interactive questions
 npx @modern-js/create components-project
 
-? Please select the solution you want to create Module Solution
-? Package Name components-demo
-? Development Language TS
-? Package Management Tool pnpm
+? Please select the solution you want to create: Npm Module
+? Package Name: components-demo
+? Development Language: TS
+? Package Manager: pnpm
 ```
 
 ---
@@ -22,10 +22,10 @@ It is recommended to use the `@modern-js/create` command to initialize an npm pr
 ```bash Interactive questions
 npx @modern-js/create components-project
 
-? Please select the solution you want to create Module Solution
-? Package Name components-demo
-? Development Language TS
-? Package Management Tool pnpm
+? Please select the solution you want to create: Npm Module
+? Package Name: components-demo
+? Development Language: TS
+? Package Manager: pnpm
 ```
 
 ---

package/docs/en/guide/intro/getting-started.md

@@ -75,10 +75,10 @@ Execute `npx @modern-js/create -h` for more command line arguments
 Next, in the issue interaction, follow the options below.
 
 ```bash
-? Please select the type of project you want to create Module
-? Please fill in the project name library
-? Please select the development language TS
-? Please select the package management tool pnpm
+? Please select the type of project you want to create: Npm Module
+? Please fill in the project name: library
+? Please select the development language: TS
+? Please select the package manager: pnpm
 ```
 
 > The project name is the value of the `"name"` field in `package.json`.

package/docs/zh/guide/advance/asset.mdx

@@ -14,7 +14,7 @@ sidebar_position: 7
 - `'.ttf'`、`'.otf'`、`'.woff'`、`'.woff2'`、`'.eot'`
 - `'.mp3'`、`'.mp4'`、`'.webm'`、`'.ogg'`、`'.wav'`、`'.flac'`、`'.aac'`、`'.mov'`
 
-对于静态文件的处理，模块工程目前支持的功能有：
+对于静态文件的处理，模块工程目前默认支持的功能有：
 
 - 设置静态资源路径为 `./assets`。
 - 对于超过 **10kb** 的文件会内联到代码中。
@@ -25,18 +25,13 @@ sidebar_position: 7
 
 ```ts ./src/asset.ts
 import img from './bg.png';
-//...
+console.log(img);
 ```
 
 ---
 
 项目源代码。
 
-```ts ./src/asset.ts
-import img from './bg.png';
-//...
-```
-
 ---
 
 如果 `bg.png` 的大小小于 10 kb，则此时产物目录结构和产物内容为。
@@ -51,12 +46,14 @@ import img from './bg.png';
 ---
 
 ```js ./dist/asset.js
-var bg_default = 'data:image/png;base64,';
-console.info(bg_default);
+var img_default = 'data:image/png;base64,';
+console.info(img_default);
 ```
 
 </CH.Code>
 
+---
+
 如果 `bg.png` 的大小大于 10 kb，则此时产物目录结构和产物内容为。
 
 <CH.Code>
@@ -71,8 +68,8 @@ console.info(bg_default);
 ---
 
 ```js ./dist/asset.js
-var bg_default = 'assets/bg.13e2aba2.png';
-console.info(bg_default);
+import img from './assets/bg.13e2aba2.png';
+console.info(img);
 ```
 
 </CH.Code>
@@ -84,61 +81,3 @@ console.info(bg_default);
 - `asset.path`：修改静态资源文件输出路径。
 - `asset.limit`：修改内联静态资源文件的阈值。
 
-## 设置 CDN 前缀
-
-如果项目运行的环境是在浏览器下，我们有可能需要静态资源托管至 CDN，然后在生产环境使用。
-
-那么此时默认生成的构建产物中，我们需要在静态资源文件的路径前面增加 CDN 的基础路径。还是看一个例子：
-
-<CH.Spotlight>
-
-```ts ./src/asset.ts
-import img from './bg.png';
-//...
-```
-
----
-
-项目源代码。
-
-```ts ./src/asset.ts
-
-```
-
----
-
-`modern.config` 配置为。
-
-```ts ./modern.config.ts
-export default defineConfig({
-  buildConfig: {
-    format: 'umd',
-    asset: {
-      publicPath: 'https://cdn/',
-    },
-  },
-});
-```
-
----
-
-如果 `bg.png` 的大小大于 10 kb，则此时产物内容为。
-
-```js ./dist/asset.js focus=7:7
-(function (global, factory) {
-  if (typeof module === 'object' && typeof module.exports === 'object')
-    factory();
-  else if (typeof define === 'function' && define.amd) define([], factory);
-  else if (
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self)
-  )
-    factory();
-})(this, function () {
-  'use strict';
-  var bg_default = 'http://cdn/assets/bg.13e2aba2.png';
-  // src/asset.tsx
-  console.info(bg_default);
-});
-```
-
-</CH.Spotlight>

package/docs/zh/guide/advance/external-dependency.mdx

@@ -13,13 +13,16 @@ sidebar_position: 4
 }
 ```
 
-而 `"dependencies"` 下的依赖通常来说是和项目代码以及构建相关的，如果这些第三方依赖声明在 `"devDependencies"` 下，那么在生产环境下就会出现缺失依赖的问题。
+`"dependencies"` 下的依赖通常来说是这个包运行所需的依赖， `"devDependencies"` 则代表着开发依赖。
 
-除了 `"dependencies"` 以外，[`"peerDependencies"`](/guide/basic/before-getting-started#peerdependencies) 也可以声明在生产环境下需要的依赖，不过它更强调项目在运行环境下存在 `"peerDependencies"` 声明的这些依赖，这类似于插件这样的机制。
+除了 `"dependencies"` 以外，[`"peerDependencies"`](/guide/basic/before-getting-started#peerdependencies) 也可以声明在生产环境下运行所需要的依赖，此时会和它的宿主共享一份依赖。
 
 ## 第三方依赖的默认处理
 
-在模块工程里，**默认情况下不会对`"dependencies"` 以及 `"peerDependencies"` 下的第三方依赖进行打包处理**，因此：
+在模块工程里，**默认情况下不会对 `"dependencies"` 以及 `"peerDependencies"` 下的第三方依赖进行打包处理**。这是因为 npm 包发布出去以后，安装 npm 包时，npm 包的 `"dependencies"` 也会被安装。
+
+- 不打包 `"dependencies"`，可以减小包产物的体积。
+- 如果需要打包，请将 `"dependencies"` 挪到 `"peerDependencies"` ，相当于对依赖进行 **prebundle** ，减小依赖安装的体积。
 
 <CH.Spotlight>
 

package/docs/zh/guide/advance/in-depth-about-build.md

@@ -25,18 +25,22 @@ sidebar_position: 1
 
 而 Bundleless 则是指对每个源文件单独进行编译构建，但是并不将它们打包在一起。每一个产物文件都可以找到与之相对应的源码文件。**Bundleless 构建的过程，也可以理解为仅对源文件进行代码转换的过程**。
 
+它们有各自的好处：
+
+- Bundle 可以减少构建产物的体积，也可以对依赖预打包，减小安装依赖的体积。提前对库进行打包，可以加快应用项目构建的速度。
+- Bundleless 则是可以保持原有的文件结构，更有利于调试和 tree shaking。
+
 在 `buildConfig` 中可以通过 [`buildConfig.buildType`](/api/config/build-config#buildtype) 来指定当前构建任务是 Bundle 还是 Bundleless。
 
 ### `input` 与 `sourceDir` 的关系
 
 [`buildConfig.input`](/api/config/build-config#input) 用于指定读取源码的文件路径或者目录路径，其默认值在 Bundle 和 Bundleless 构建过程中有所不同：
 
-- 当 `buildType: 'bundle'` 的时候，`input` 默认值为 `['src/index.ts']`
+- 当 `buildType: 'bundle'` 的时候，`input` 默认值为 `src/index.(j|t)sx?`
 - 当 `buildType: 'bundleless'` 的时候，`input` 默认值为 `['src']`
-  > 实际上，在 `buildType: 'bundle'` 的时候，构建工具会检测是否存在符合 `src/index.(j|t)sx?` 这个名称规则的文件，并将其作为入口文件。
 
 :::warning {title=注意}
-建议不要在 Bundleless 构建过程中指定多个源码文件目录，可能出现不符合预期的结果。目前多个源码目录的 Bundleless 构建还处于不稳定阶段。
+建议不要在 Bundleless 构建过程中指定多个源码文件目录，这可能会导致产物里的相对路径不正确。
 :::
 
 从默认值上我们可以知道：**Bundle 构建一般可以指定文件路径作为构建的入口，而 Bundleless 构建则更期望使用目录路径寻找源文件**。
@@ -70,7 +74,7 @@ export default defineConfig({
 一般来说：
 
 - **在 Bundleless 构建过程中，`sourceDir` 与 `input` 的值要保持一致，它们的默认值都是 `src`**。
-- 在 Bundle 构建过程中，很少需要使用 `sourceDir`。
+- 在 Bundle 构建过程中，无需使用 `sourceDir`。
 
 ### 类型文件
 

package/docs/zh/guide/best-practices/components.mdx

@@ -13,10 +13,10 @@ sidebar_position: 1
 ```bash 交互式问题
 npx @modern-js/create components-project
 
-? 请选择你想创建的工程类型 模块
-? 请填写项目名称 components-demo
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写项目名称：components-demo
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
 ```
 
 ---
@@ -26,10 +26,10 @@ npx @modern-js/create components-project
 ```bash 交互式问题
 npx @modern-js/create components-project
 
-? 请选择你想创建的工程类型 模块
-? 请填写项目名称 components-demo
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写项目名称：components-demo
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
 ```
 
 ---

package/docs/zh/guide/intro/getting-started.md

@@ -73,10 +73,10 @@ npx @modern-js/create your-project-dir-name
 接着在问题交互中，按照如下选择：
 
 ```bash
-? 请选择你想创建的工程类型 模块
-? 请填写项目名称 library
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写项目名称：library
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
 ```
 
 > 项目名称为 `package.json` 中的 `"name"` 字段值。

package/package.json

@@ -5,15 +5,15 @@
   "bugs": "https://github.com/web-infra-dev/modern.js/issues",
   "repository": "web-infra-dev/modern.js",
   "license": "MIT",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "main": "index.js",
   "dependencies": {
     "@code-hike/mdx": "^0.7.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "shiki": "^0.11.1",
-    "@modern-js/doc-plugin-auto-sidebar": "2.8.0",
-    "@modern-js/doc-tools": "2.8.0"
+    "@modern-js/doc-plugin-auto-sidebar": "2.9.0",
+    "@modern-js/doc-tools": "2.9.0"
   },
   "scripts": {
     "dev": "modern dev",