@modern-js/module-tools-docs 2.46.1 → 2.47.0

package/CHANGELOG.md

@@ -1,5 +1,7 @@
 # @modern-js/module-tools-docs
 
+## 2.47.0
+
 ## 2.46.1
 
 ## 2.46.0

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

@@ -1282,7 +1282,9 @@ Set `inject` to `true` to enable this feature:
 ```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
-    inject: true,
+    style: {
+      inject: true,
+    },
   },
 });
 ```

package/docs/en/guide/basic/{publish-your-project.md → publish-your-project.mdx}

@@ -7,7 +7,13 @@ sidebar_position: 7
 An npm-type module project release process consists of two phases.
 
 - The first phase is during development, where the developer needs to provide a change file to record changes that need to be released.
-- The second phase is during release, where Modern.js Module can collect all the change files to update the version, update the release log, and release new packages to the [npm Registry](https://www.npmjs.com/).
+- The second phase is during release, collect all the change files to update the version, update the release log, and release new packages to the [npm Registry](https://www.npmjs.com/).
+
+Modern.js Module provides a set of version management and release solutions, which are suitable for single-package scenarios. For npm packages in monorepo, you need to follow the strategies provided by various monorepo solutions.
+
+import PublishEMO from '@site-docs/components/publish-emo';
+
+<PublishEMO />
 
 ## Tracking changes
 

package/docs/en/guide/basic/use-module-doc.mdx

@@ -56,7 +56,7 @@ The sidebars corresponding in turn to the above file paths and routing paths are
 ### Configure sidebar
 
 As shown in the figure above, the module documentation has automatically generated sidebars for file system routing, where the text of each column of the sidebar is determined by the file's first level title or directory name.
-If you need to customize the sidebar, please use [_meta.json](https://rspress.dev/guide/basic/auto-nav-sidebar.html) or configure [sidebar](https://rspress.dev/api/config/config-theme.html#sidebar) directly.
+If you need to customize the sidebar, please use [\_meta.json](https://rspress.dev/guide/basic/auto-nav-sidebar.html) or configure [sidebar](https://rspress.dev/api/config/config-theme.html#sidebar) directly.
 
 :::info
 If your document directory structure complies with internationalization, for example:
@@ -146,9 +146,9 @@ export default defineConfig({
     modulePluginDoc({
       /**
        * Select the preview method
-       * @default web
+       * @default internal
        */
-      previewMode: 'mobile',
+      previewMode: 'iframe',
       /**
        * Select iframe position
        * @default 'follow'
@@ -167,12 +167,12 @@ If you only want to change the way a particular `jsx` and `tsx` block is preview
 // The content here will not be rendered
 ```
 
-```jsx web
-// Used to render desktop components
+```jsx internal
+// Used to render components in documentation
 ```
 
-```jsx mobile
-// Used to render mobile components
+```jsx iframe
+// Used to render components in iframe
 ```
 ````
 
@@ -186,6 +186,12 @@ If our demo is very complex, then it is recommended to write the demo separately
 <code src="/path/demo.tsx"></code>
 ```
 
+This also supports setting the preview method for each individual code block, for example:
+
+```mdx
+<code src="/path/demo.tsx" previewMode="iframe"></code>
+```
+
 ## Using built-in components
 
 The plugin implements some built-in components internally so that you can develop module documentation more easily.
@@ -239,7 +245,20 @@ export const Button = (props?: ButtonProps) => {};
 ```
 
 The above is a standard writeup where `ButtonProps` will be extracted into the table and `Button` will be the title of the table.
-If you use the default export, the filename will be used as the form title. The generated content is as follows:
+If you use the default export, the filename will be used as the form title.
+
+Notice that export features declared elsewhere are not available.
+
+```tsx
+const A = () => {};
+
+export { A }; // wrong
+export default A; // wrong
+export const B = () => {}; // right
+export default () => {}; // right
+```
+
+The generated content is as follows:
 
 ```mdx
 ### ButtonTest
@@ -261,6 +280,12 @@ If React types are used in Props, you need to add the types in tsconfig.json, ot
 }
 ```
 
+The best way is that you import the type directly:
+
+```tsx
+import { FC } from 'react';
+```
+
 :::
 
 - `documentation` is used in tool library scenarios to parse JSDoc annotations.
@@ -398,10 +423,10 @@ type ParseToolOptions = {
 
 ### previewMode
 
-- Type:`'mobile' | 'web'`
-- Default: `'web'`
+- Type:`'iframe' | 'internal'`
+- Default: `'internal'`
 
-In case of `web`, the component will be rendered directly in the page, otherwise it will be loaded through an iframe.
+In case of `internal`, the component will be rendered directly in the page, otherwise it will be loaded through an iframe.
 
 ### deprecated: languages
 
@@ -417,6 +442,7 @@ or directly configure [sidebar](https://rspress.dev/api/config/config-theme.html
 :::
 
 ## Scripts
+
 - `modern dev`: Start dev server for doc site.
 - `modern build --platform`: Build doc site in production, by default output directories is `doc_build`.
 

package/docs/en/guide/basic/using-storybook.mdx

@@ -100,8 +100,6 @@ export default config;
 
 Note that in the above configuration, the reactDocgen configuration has been changed because Rspack currently does not support @storybook/react-docgen-typescript-plugin.
 
-Before starting, make sure that you have installed the @modern-js/builder-rspack-provider package.
-
 ### Configurations
 
 There are some separate configurations in `.storybook/main.js`.
@@ -111,7 +109,7 @@ There are some separate configurations in `.storybook/main.js`.
 - **Type**: `'webpack' | 'rspack'`
 - **Default**: `webpack`
 
-Specify the underlying build tool to use either Webpack or Rspack. Please make sure to install the corresponding provider. To use Webpack, install @modern-js/builder-webpack-provider. To use Rspack, install @modern-js/builder-rspack-provider.
+Specify the underlying bundler to use either Webpack or Rspack.
 
 Example:
 
@@ -133,7 +131,7 @@ export default config;
 - **Type**: `BuilderConfig`
 - **Default**: `undefined`
 
-To modify the configuration of the builder.
+The Storybook build capability of Modern.js is provided by [Rsbuild](https://rsbuild.dev/), and the Rsbuild configuration can be modified through builderConfig.
 
 ```javascript filename='.storybook/main.js'
 const config = {
@@ -155,7 +153,7 @@ export default config;
 
 ### Command
 
-@modern-js/storybook 代理了部分 storybook cli 的命令
+@modern-js/storybook proxies some storybook cli commands
 
 #### storybook dev
 

package/docs/en/guide/faq/build.mdx

@@ -97,6 +97,12 @@ export const libs = {
 
 In this case `babel-plugin-import` may also cause `Comps` to become `undefined`. So you need to remove the corresponding `babel-plugin-import` as well.
 
+### Cannot find module http
+
+If the output reports an error like `Cannot find module 'http'` at browser runtime, it means that your output has bundled node modules.
+This may occur if some of your dependencies support both browser and node, such as `axios`, in which case you only need to set the [platform](/api/config/build-config.html/#platform) to `browser`.
+If some third-party packages don't support the browser, you may need to manually inject [node polyfill](/plugins/official-list/plugin-node-polyfill).
+
 ## Exceptions FAQ
 
 import BuildExceptionFAQ from '@site-docs-en/components/faq-build-exception';
@@ -198,9 +204,9 @@ module.exports = {
                 return options;
               });
           },
-        }
-      }
-    }
+        },
+      },
+    },
   },
 };
 ```
@@ -212,7 +218,7 @@ For source code files, it is recommended to fix the type problem, which can bett
 
 1. enable [skipLibCheck](https://www.typescriptlang.org/tsconfig#skipLibCheck) to skip the d.ts check of the thrid-party package.
 2. If the package exports ts files directly, skipLibCheck will not work because it can only skip the d.ts check,
-so you can only turn off [dts.abortOnError](/api/config/build-config.html#dtsabortonerror) to ignore these errors.
+   so you can only turn off [dts.abortOnError](/api/config/build-config.html#dtsabortonerror) to ignore these errors.
 
 ### Bundle DTS failed
 
@@ -238,6 +244,36 @@ import BuildOtherFAQ from '@site-docs-en/components/faq-build-other';
 
 <BuildOtherFAQ />
 
+### How to skip the pre-processing of less/scss files with bundleless
+
+Bundleless is a single-file compilation method. You just need to remove your less/scss files from the entry and copy them to the output.
+Note that we will also rewrite the moduleId of js referencing less/scss, turn it off through the [redirect](/api/config/build-config#redirect) plugin.
+
+Below is an example of skipping less file processing. You will find that all less files in src are copied to dist and the relative path is preserved.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  buildConfig: {
+    buildType: 'bundleless',
+    input: ['src', '!src/**/*.less'],
+    redirect: {
+      style: false,
+    },
+    copy: {
+      patterns: [
+        {
+          from: './**/*.less',
+          to: './',
+        },
+      ],
+      options: {
+        enableCopySync: true,
+      },
+    },
+  },
+});
+```
+
 ### Add additional compilation feature
 
 The Modern.js Module is based on the esbuild implementation, so if you have special needs or want to add additional compilation capabilities, you can do so by implementing the esbuild plugin.

package/docs/en/plugins/official-list/overview.md

@@ -1,6 +1,6 @@
 # Overview
 
-## Official Plugin
+## Official Plugins
 
 * [@modern-js/plugin-module-import](./plugin-import.md)：Use SWC to provide the same ability as [`babel-plugin-import`](https://github.com/umijs/babel-plugin-import).
 * [@modern-js/plugin-module-banner](./plugin-banner.md)：Add custom content, such as copyright information, to the top and bottom of each JS and CSS file.

package/docs/en/plugins/official-list/plugin-vue.mdx

@@ -8,6 +8,7 @@ Notice that we have some limitation:
 1. The current implementation of this plugin integrates directly with the community plugin and therefore does not support writing jsx/tsx in sfc.
 2. If you want to generate d.ts for the components, please use the official recommendation [vue-tsc](https://www.npmjs.com/package/vue-tsc).
 3. Only support bundle, we recommend to set input to `['src/**/*.vue']` or `['src/index.ts']`.
+
 :::
 
 ## Quick start

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

@@ -485,7 +485,6 @@ export default defineConfig({
 });
 ```
 
-
 ## dts.only
 
 是否在构建时只生成类型文件，不生成 JavaScript 产物文件。
@@ -1281,7 +1280,9 @@ export default defineConfig({
 ```js title="modern.config.ts"
 export default defineConfig({
   buildConfig: {
-    inject: true,
+    style: {
+      inject: true,
+    },
   },
 });
 ```

package/docs/zh/guide/basic/{publish-your-project.md → publish-your-project.mdx}

@@ -7,7 +7,13 @@ sidebar_position: 7
 一个 npm 类型的模块项目发布流程包含了两个阶段：
 
 - 第一阶段是在开发期间，开发者需要提供变更文件，该文件记录了在发布期间需要的变更内容；
-- 第二阶段是在发布期间，Modern.js Module 会收集所有的变更文件来更新版本、更新发布日志，并发布新的包到 [npm Registry](https://www.npmjs.com/) 上。
+- 第二阶段是在发布期间，需要收集所有的变更文件来更新版本、更新发布日志，并发布新的包到 [npm Registry](https://www.npmjs.com/) 上。
+
+Modern.js Module 提供了一套版本管理与发布的方案，这适用于单包场景。对于 monorepo 里的 npm 包你需要遵循各类 monorepo 解决方案提供的策略。
+
+import PublishEMO from '@site-docs/components/publish-emo';
+
+<PublishEMO />
 
 ## 跟踪变更
 

package/docs/zh/guide/basic/use-module-doc.mdx

@@ -55,10 +55,11 @@ docs
 ### 配置侧边栏
 
 如上图所示，模块文档已经为文件系统路由自动生成了侧边栏，其中侧边栏每一栏的文本是由文件的一级标题或者目录名决定。
-如果你需要自定义侧边栏，请使用 [_meta.json](https://rspress.dev/zh/guide/basic/auto-nav-sidebar.html) 或者直接配置 [sidebar](https://rspress.dev/zh/api/config/config-theme.html#sidebar)。
+如果你需要自定义侧边栏，请使用 [\_meta.json](https://rspress.dev/zh/guide/basic/auto-nav-sidebar.html) 或者直接配置 [sidebar](https://rspress.dev/zh/api/config/config-theme.html#sidebar)。
 
 :::info
 如果你的文档目录结构是符合国际化的，例如：
+
 ```bash
 docs
 ├── en
@@ -68,6 +69,7 @@ docs
     ├── button.mdx
     ├── index.mdx
 ```
+
 你需要按照[国际化](https://rspress.dev/zh/guide/default-theme/i18n.html)章节，同时配置 `lang` 和 `locales`，否则模块自动生成的侧边栏不会处理 `zh` 和 `en` 这两个目录。
 :::
 
@@ -139,9 +141,9 @@ export default defineConfig({
     modulePluginDoc({
       /**
        * 选择预览方式
-       * @default web
+       * @default internal
        */
-      previewMode: 'mobile',
+      previewMode: 'iframe',
       /**
        * 设置 iframe 的位置
        * @default 'follow'
@@ -160,12 +162,12 @@ export default defineConfig({
 // 这里的内容不会被渲染
 ```
 
-```jsx web
-// 用来渲染桌面端组件
+```jsx internal
+// 内置在文档内容里渲染
 ```
 
-```jsx mobile
-// 用来渲染移动端组件
+```jsx iframe
+// 使用 iframe 渲染
 ```
 ````
 
@@ -179,6 +181,12 @@ export default defineConfig({
 <code src="/path/demo.tsx"></code>
 ```
 
+这同样支持单独设置代码块的预览方式，例如：
+
+```mdx
+<code src="/path/demo.tsx" previewMode="iframe"></code>
+```
+
 ## 使用内置组件
 
 插件内部实现了一部分内置组件，以便于你可以更轻松地开发模块文档。
@@ -231,8 +239,20 @@ export type ButtonProps = {
 export const Button = (props?: ButtonProps) => {};
 ```
 
-上面是一个标准写法，其中 `ButtonProps` 将被提取至表格中， `Button` 作为表格的标题。
-如果使用默认导出，文件名将作为表格标题。生成的内容如下：
+上面是一个标准写法，其中 `ButtonProps` 将被提取至表格中， `Button` 作为表格的标题。如果使用默认导出，文件名将作为表格标题。
+
+需要注意的是，export 导出事先定义的特性将不会被解析。
+
+```tsx
+const A = () => {};
+
+export { A }; // wrong
+export default A; // wrong
+export const B = () => {}; // right
+export default () => {}; // right
+```
+
+生成的内容如下：
 
 ```mdx
 ### ButtonTest
@@ -245,15 +265,22 @@ export const Button = (props?: ButtonProps) => {};
 
 :::warning
 如果 Props 里使用了 React 的类型，你需要在 tsconfig.json 里添加 types ，否则会解析不到 React 命名空间下的类型。
+
 ```json
 {
   "compilerOptions": {
-    "types": ["react"],
-  },
+    "types": ["react"]
+  }
 }
 ```
-:::
 
+更好的方式是直接引用类型，例如
+
+```tsx
+import { FC } from 'react';
+```
+
+:::
 
 - `documentation`适用于工具库场景，用来解析 JSDoc 注释。
 
@@ -394,10 +421,10 @@ type ParseToolOptions = {
 
 代码块预览方式。
 
-- 类型：`'mobile' | 'web'`
-- 默认值: `'web'`
+- 类型：`'internal' | 'iframe'`
+- 默认值: `'internal'`
 
-`web`时，代码块内容将会直接渲染在页面中，反之将会通过 iframe 加载。
+`internal`时，代码块内容将会直接渲染在页面中，反之将会通过 iframe 加载。
 
 ### deprecated: languages
 
@@ -408,11 +435,12 @@ type ParseToolOptions = {
 ### deprecated: useModuleSidebar
 
 :::warning
-从 MAJOR_VERSION.44.0 版本开始，内部实现了嗅探机制，请直接使用 [_meta.json](https://rspress.dev/zh/guide/basic/auto-nav-sidebar.html)
+从 MAJOR_VERSION.44.0 版本开始，内部实现了嗅探机制，请直接使用 [\_meta.json](https://rspress.dev/zh/guide/basic/auto-nav-sidebar.html)
 或者直接配置 [sidebar](https://rspress.dev/zh/api/config/config-theme.html#sidebar) 来实现自定义侧边栏。
 :::
 
 ## 命令行
+
 - `modern dev`: 启动文档站本地开发。
 - `modern build --platform`: 构建生产环境产物。
 

package/docs/zh/guide/basic/using-storybook.mdx

@@ -100,7 +100,6 @@ export default config;
 ```
 
 注意上面配置中，更改了 reactDocgen 配置，因为 Rspack 目前还不支持 @storybook/react-docgen-typescript-plugin。
-在启动前，确保已安装 @modern-js/builder-rspack-provider 包。
 
 ### 配置
 
@@ -111,7 +110,7 @@ export default config;
 - **类型**: `'webpack' | 'rspack'`
 - **默认值**: `webpack`
 
-指定底层构建工具使用 Webpack 还是 Rspack。请确保安装了对应的 provider，使用 Webpack 请安装 @modern-js/builder-webpack-provider，使用 Rspack 请安装 @modern-js/builder-rspack-provider。
+指定底层打包工具使用 Webpack 还是 Rspack。
 
 ```javascript filename='.storybook/main.js'
 const config = {
@@ -131,7 +130,7 @@ export default config;
 - **类型**: `BuilderConfig`
 - **默认值**: `undefined`
 
-更改[Modern.js builder](https://modernjs.dev/builder/guide/basic/builder-config.html) 的配置
+Modern.js 的 Storybook 构建能力由 [Rsbuild](https://rsbuild.dev/) 提供，可通过 builderConfig 修改 Rsbuild 构建配置。
 
 ```javascript filename='.storybook/main.js'
 const config = {
@@ -165,14 +164,14 @@ export default config;
 
 ### 配置文件
 
-配置文件中除了 Modern.js builder 配置还包含一个额外的字段，builderPlugins，方便使用 builder 插件，例如启用 SWC 编译。
+配置文件中除了 Rsbuild 配置还包含一个额外的字段，builderPlugins，方便使用 Rsbuild 插件，例如启用 SWC 编译。
 
 ```typescript filename='modern.config.ts'
 import { defineConfig } from '@modern-js/storybook';
-import { builderPluginSwc } from '@modern-js/builder-plugin-swc';
+import { pluginSwc } from '@rsbuild/plugin-swc';
 
 const config = defineConfig({
-  builderPlugins: [builderPluginSwc()],
+  builderPlugins: [pluginSwc()],
 });
 
 export default config;

package/docs/zh/guide/faq/build.mdx

@@ -97,6 +97,12 @@ export const libs = {
 
 此时 `babel-plugin-import` 也可能会导致 `Comps` 变为 `undefined`。因此也需要移除对应的 `babel-plugin-import`。
 
+### Cannot find module http
+
+如果产物在浏览器运行时报了类似 `Cannot find module 'http'` 的错误，说明你的产物打包进了 node 模块。
+这可能会发生于你的依赖里有一些同时支持 browser 和 node 的三方包，例如 `axios`，此时只需要将 [platform](/api/config/build-config.html/#platform) 设置为 `browser` 即可。
+如果一些三方包不支持 browser, 你可能需要手动注入 [node polyfill](/plugins/official-list/plugin-node-polyfill)。
+
 ## 异常类问题
 
 import BuildExceptionFAQ from '@site-docs/components/faq-build-exception';
@@ -235,6 +241,36 @@ import BuildOtherFAQ from '@site-docs/components/faq-build-other';
 
 <BuildOtherFAQ />
 
+### bundleless 如何跳过对 less / scss 文件的预处理
+
+bundleless 是单文件编译的方式，只需要将你的 less / scss 文件从入口里移除并且将其拷贝到产物里即可。
+注意我们还会把 js 引用 less / scss 的 moduleId 进行改写，你可以通过 [redirect](/api/config/build-config#redirect) 配置关闭它。
+
+下面是一个跳过 less 文件处理的例子，你会发现 src 里面所有的 less 文件都被拷贝到 dist 里并且保留了一致的相对路径。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  buildType: 'bundleless',
+  buildConfig: {
+    input: ['src', '!src/**/*.less'],
+    redirect: {
+      style: false,
+    },
+    copy: {
+      patterns: [
+        {
+          from: './**/*.less',
+          to: './',
+        },
+      ],
+      options: {
+        enableCopySync: true,
+      },
+    },
+  },
+});
+```
+
 ### 增加额外的编译能力
 
 Modern.js Module 基于 esbuild 实现，因此如果有特殊需求或者想要增加额外的编译能力，可以通过实现 esbuild 插件来解决。

package/docs/zh/plugins/official-list/plugin-vue.mdx

@@ -8,6 +8,7 @@ Vue 插件提供了对 Vue 3 组件构建的支持，插件内部集成了 [esbu
 1. 目前此插件的实现是直接集成社区插件，因此不支持在 sfc 里写 jsx/tsx。
 2. 如果要为组件生成 d.ts，请使用官方推荐方式 [vue-tsc](https://www.npmjs.com/package/vue-tsc)。
 3. 仅支持打包场景，推荐将 input 设置为 `['src/**/*.vue']` 或者 `['src/index.ts']`。
+
 :::
 
 ## 快速开始

package/package.json

@@ -9,14 +9,14 @@
     "directory": "packages/document/module-doc"
   },
   "license": "MIT",
-  "version": "2.46.1",
+  "version": "2.47.0",
   "main": "index.js",
   "devDependencies": {
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "rspress": "1.10.0",
-    "@rspress/shared": "1.10.0",
-    "@modern-js/doc-plugin-auto-sidebar": "2.46.1"
+    "rspress": "1.11.2",
+    "@rspress/shared": "1.11.2",
+    "@modern-js/doc-plugin-auto-sidebar": "2.47.0"
   },
   "scripts": {
     "dev": "rspress dev",