@modern-js/module-tools-docs 2.28.0 → 2.30.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @modern-js/module-tools-docs
 
+## 2.30.0
+
+### Patch Changes
+
+- Updated dependencies [c03be09]
+  - @modern-js/doc-tools@2.30.0
+  - @modern-js/doc-plugin-auto-sidebar@2.30.0
+
+## 2.29.0
+
+### Patch Changes
+
+- @modern-js/doc-plugin-auto-sidebar@2.29.0
+- @modern-js/doc-tools@2.29.0
+
 ## 2.28.0
 
 ### Patch Changes

package/docs/en/api/config/build-config.mdx

@@ -217,7 +217,7 @@ Whether to require peerDep dependencies for external projects
 The build type, `bundle` will package your code, `bundleless` will only do the code conversion
 
 - **Type**: `'bundle' | 'bundleless'`
-- **Default**: `bundle`
+- **Default**: `'bundle'`
 
 ## copy
 
@@ -346,15 +346,37 @@ When this configuration is disabled, there is no guarantee that the type files w
 The output path of the dts file, based on [outDir](/api/config/build-config#outDir)
 
 - **Type**: `string`
-- **Default**: `. /types`
+- **Default**: `./`
+
+For example, output to the `types` directory under the `outDir`:
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    dts: {
+      distPath: './types',
+    },
+  },
+});
+```
 
 ## dts.only
 
-Generate only dts files, not js files
+Whether to generate only type files during the build process without generating JavaScript output files.
 
 - **Type**: `boolean`
 - **Default**: `false`
 
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    dts: {
+      only: true,
+    },
+  },
+});
+```
+
 ## dts.respectExternal
 
 When set to `false`, the type of third-party packages will be excluded from the bundle, when set to `true`, it will determine whether third-party types need to be bundled based on [externals](#externals).
@@ -365,6 +387,16 @@ So we can avoid it with this configuration.
 - **Type**: `boolean`
 - **Default**: `true`
 
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    dts: {
+      respectExternal: false,
+    },
+  },
+});
+```
+
 ## dts.tsconfigPath
 
 Path to the tsconfig file
@@ -372,11 +404,22 @@ Path to the tsconfig file
 - **Type**: `string`
 - **Default**: `. /tsconfig.json`
 
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    dts: {
+      tsconfigPath: './other-tsconfig.json',
+    },
+  },
+});
+```
+
 ## esbuildOptions
 
 Used to modify the [esbuild configuration](https://esbuild.github.io/api/).
 
 - **Type**: `Function`
+- **Build Type**: `Only supported for buildType: 'bundle'`
 - **Default**: `c => c`
 
 For example, if we need to modify the file extension of the generated files:
@@ -645,17 +688,33 @@ export default {
 
 ## outDir
 
-Specifies the output directory of the build
+Specifies the output directory of the build.
 
 - **Type**: `string`
-- **Default**: `dist`
+- **Default**: `./dist`
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    outDir: './dist/esm',
+  },
+});
+```
 
 ## platform
 
 Generates code for the node environment by default, you can also specify `browser` which will generate code for the browser environment
 
 - **Type**: `'browser' | 'node'`
-- **Default**: `node`
+- **Default**: `'node'`
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    platform: 'browser',
+  },
+});
+```
 
 ## redirect
 
@@ -886,12 +945,38 @@ export default {
 
 ## style.postcss
 
-- plugins
-- processOptions
+Used to configure options for PostCSS. The provided values will be merged with the default configuration using `Object.assign`. Note that `Object.assign` performs a shallow copy, so it will completely override the built-in `plugins` array.
+
+For detailed configuration, please refer to [PostCSS](https://github.com/postcss/postcss#options).
+
+- **Type**:
+
+```ts
+type PostcssOptions = {
+  processOptions?: ProcessOptions;
+  plugins?: AcceptedPlugin[];
+};
+```
+
+- **Default**:
 
-See [PostCSS](https://github.com/postcss/postcss#options) for detailed configuration
+```ts
+const defaultConfig = {
+  plugins: [
+    // The following plugins are enabled by default
+    require('postcss-flexbugs-fixes'),
+    require('postcss-media-minmax'),
+    require('postcss-nesting'),
+    // The following plugins are only enabled when the target is `es5`
+    require('postcss-custom-properties'),
+    require('postcss-initial'),
+    require('postcss-page-break'),
+    require('postcss-font-variant'),
+  ],
+};
+```
 
-**Basic usage：**
+- **Example**:
 
 ```js modern.config.ts
 export default defineConfig({
@@ -1021,6 +1106,7 @@ const tailwind = {
   ],
 };
 ```
+
 </details>
 
 When the value is of type `object`, it is merged with the default configuration via `Object.assign`.

package/docs/en/api/config/build-preset.mdx

@@ -100,6 +100,7 @@ export const buildConfig = [
   {
     format: 'umd',
     target: 'es6',
+    platform: 'browser',
     buildType: 'bundle',
     outDir: './dist/umd',
   },
@@ -183,6 +184,7 @@ export const buildConfig = [
   {
     format: 'umd',
     target: 'es6',
+    platform: 'browser',
     buildType: 'bundle',
     outDir: './dist/umd',
   },

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

@@ -6,7 +6,7 @@ sidebar_position: 3
 
 ## 3 minute demo
 
-Want to experience Module Tools in action? The only prerequisite you need is [Node.js LTS](https://github.com/nodejs/Release) and make sure your Node version is **>= 14.18.0**.We recommend using the LTS version of Node.js 16.
+Want to experience Module Tools in action? The only prerequisite you need is [Node.js LTS](https://github.com/nodejs/Release) and make sure your Node version is **>= 14.18.0**.We recommend using the LTS version of Node.js 18.
 
 ### Create new project
 
@@ -73,6 +73,25 @@ Finally, add the command `"build": "modern build"` to the project's `package.jso
 
 If your project has a `src/index.(js|jsx)` file or both `src/index.(ts|tsx)` and `tsconfig.json` files, then congratulations you can run the `npm run build` command directly to build your project with Module Tools.
 
+### Core npm Package
+
+`@modern-js/module-tools` is the core npm package of Module Tools, providing the following capabilities:
+
+- It offers commonly used CLI commands such as `modern dev`, `modern build`, and more.
+- It integrates Modern.js Core, providing capabilities for configuration parsing, plugin loading, and more.
+- It integrates esbuild and SWC, providing build capabilities.
+- It integrates some commonly used plugins, such as `plugin-lint`, `plugin-changeset`, and others.
+
+`@modern-js/module-tools` is implemented based on the plugin system of Modern.js. Essentially, it is a plugin. Therefore, you need to register `moduleTools` in the `plugins` field of the configuration file:
+
+```ts modern.config.ts
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  plugins: [moduleTools()],
+});
+```
+
 ### View official example
 
 **If you want to see the complete project using the modular engineering scheme, you can execute the following command**.

package/docs/zh/api/config/build-config.mdx

@@ -218,7 +218,7 @@ export default defineConfig({
 构建类型，`bundle` 会打包你的代码，`bundleless` 只做代码的转换。
 
 - 类型： `'bundle' | 'bundleless'`
-- 默认值： `bundle`
+- 默认值： `'bundle'`
 
 ## copy
 
@@ -345,16 +345,38 @@ export default defineConfig({
 
 类型文件的输出路径，基于 [outDir](/api/config/build-config#outDir) 进行输出。
 
-- 类型: `string`
-- 默认值: `./types`
+- 类型： `string`
+- 默认值： `./`
+
+比如输出到 `outDir` 下面的 `types` 目录：
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    dts: {
+      distPath: './types',
+    },
+  },
+});
+```
 
 ## dts.only
 
-只生成类型文件，不生成 js 文件。
+是否在构建时只生成类型文件，不生成 JavaScript 产物文件。
 
 - 类型： `boolean`
 - 默认值： `false`
 
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    dts: {
+      only: true,
+    },
+  },
+});
+```
+
 ## dts.respectExternal
 
 当设为 `false` 时，不会打包任何三方包类型，设为 `true` 时，会根据 [externals](#externals) 来决定是否需要打包三方类型。
@@ -364,6 +386,16 @@ export default defineConfig({
 - 类型： `boolean`
 - 默认值： `true`
 
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    dts: {
+      respectExternal: false,
+    },
+  },
+});
+```
+
 ## dts.tsconfigPath
 
 TypeScript 配置文件的路径。
@@ -371,12 +403,22 @@ TypeScript 配置文件的路径。
 - 类型： `string`
 - 默认值： `./tsconfig.json`
 
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    dts: {
+      tsconfigPath: './other-tsconfig.json',
+    },
+  },
+});
+```
+
 ## esbuildOptions
 
 用于修改底层的 [esbuild 配置](https://esbuild.github.io/api/)。
 
-- 类型: `Function`
-- 默认值: `c => c`
+- 类型： `Function`
+- 默认值： `c => c`
 
 例如，我们需要修改生成文件的后缀：
 
@@ -645,17 +687,33 @@ export default defineConfig({
 
 ## outDir
 
-指定构建的输出目录
+指定构建的输出目录。
 
-- 类型: `string`
-- 默认值: `dist`
+- 类型： `string`
+- 默认值： `./dist`
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    outDir: './dist/esm',
+  },
+});
+```
 
 ## platform
 
 默认生成用于 Node.js 环境下的代码，你也可以指定为 `browser`，会生成用于浏览器环境的代码。
 
 - 类型： `'browser' | 'node'`
-- 默认值： `node`
+- 默认值： `'node'`
+
+```js modern.config.ts
+export default defineConfig({
+  buildConfig: {
+    platform: 'browser',
+  },
+});
+```
 
 ## redirect
 
@@ -887,12 +945,38 @@ export default defineConfig({
 
 ## style.postcss
 
-- plugins
-- processOptions
+用于配置 PostCSS 的选项，传入的值会与默认配置通过 `Object.assign` 合并。注意 `Object.assign` 是浅拷贝，因此会完全覆盖内置的 plugins 数组。
 
-详细配置查看 [PostCSS](https://github.com/postcss/postcss#options)。
+详细配置请查看 [PostCSS](https://github.com/postcss/postcss#options)。
 
-**基础使用：**
+- 类型：
+
+```ts
+type PostcssOptions = {
+  processOptions?: ProcessOptions;
+  plugins?: AcceptedPlugin[];
+};
+```
+
+- 默认值：
+
+```ts
+const defaultConfig = {
+  plugins: [
+    // 以下插件默认启用
+    require('postcss-flexbugs-fixes'),
+    require('postcss-media-minmax'),
+    require('postcss-nesting'),
+    // 以下插件仅在 target 为 `es5` 时启用
+    require('postcss-custom-properties'),
+    require('postcss-initial'),
+    require('postcss-page-break'),
+    require('postcss-font-variant'),
+  ],
+};
+```
+
+- 示例：
 
 ```js modern.config.ts
 export default defineConfig({
@@ -1024,6 +1108,7 @@ const tailwind = {
   ],
 };
 ```
+
 </details>
 
 值为 `object` 类型时，与默认配置通过 `Object.assign` 合并。

package/docs/zh/api/config/build-preset.mdx

@@ -100,6 +100,7 @@ export const buildConfig = [
   {
     format: 'umd',
     target: 'es6',
+    platform: 'browser',
     buildType: 'bundle',
     outDir: './dist/umd',
   },
@@ -183,6 +184,7 @@ export const buildConfig = [
   {
     format: 'umd',
     target: 'es6',
+    platform: 'browser',
     buildType: 'bundle',
     outDir: './dist/umd',
   },

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

@@ -6,7 +6,7 @@ sidebar_position: 3
 
 ## 三分钟快速上手
 
-想要实际体验 Module Tools？首先需要安装 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 **14.18.0**。我们推荐使用 Node.js 16 的 LTS 版本。
+想要实际体验 Module Tools？首先需要安装 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 **14.18.0**。我们推荐使用 Node.js 18 的 LTS 版本。
 
 ### 创建新项目
 
@@ -70,6 +70,25 @@ export default defineConfig({
 
 如果你的项目存在 `src/index.(js|jsx)` 文件或者同时存在 `src/index.(ts|tsx)` 和 `tsconfig.json` 文件，那么恭喜你可以运行直接运行 `npm run build` 来使用 Module Tools 构建你的项目了。
 
+### 核心 npm 包
+
+`@modern-js/module-tools` 是 Module Tools 的核心 npm 包，主要提供以下能力：
+
+- 提供 `modern dev`, `modern build` 等常用的 CLI 命令。
+- 集成 Modern.js Core，提供配置解析、插件加载等能力。
+- 集成 esbuild 和 SWC，提供构建能力。
+- 集成一些最为常用的插件，比如 `plugin-lint`、`plugin-changeset` 等。
+
+`@modern-js/module-tools` 是基于 Modern.js 的插件体系实现的，本质上是一个插件，因此你需要在配置文件的 `plugins` 字段中注册 `moduleTools`：
+
+```ts modern.config.ts
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
+
+export default defineConfig({
+  plugins: [moduleTools()],
+});
+```
+
 ### 查看官方示例
 
 **如果你想要看看使用了模块工程方案的完整项目，可以执行以下命令**：

package/package.json

@@ -9,15 +9,15 @@
     "directory": "packages/document/module-doc"
   },
   "license": "MIT",
-  "version": "2.28.0",
+  "version": "2.30.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.28.0",
-    "@modern-js/doc-tools": "2.28.0"
+    "@modern-js/doc-plugin-auto-sidebar": "2.30.0",
+    "@modern-js/doc-tools": "2.30.0"
   },
   "scripts": {
     "dev": "modern dev",