@modern-js/module-tools-docs 2.25.0 → 2.25.2-beta.0

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

@@ -605,7 +605,7 @@ When adding styles using HTML class names, by default Tailwind will not only add
 
 For the following code, there is a big difference between the bundle and bundleless modes of building products.
 
-> The so-called bundle and bundleless can be found in [[Bundle and Bundleless]](/en/guide/advance/in-depth-about-build#bundle- and-bundleless)
+> The so-called bundle and bundleless can be found in ["Bundle and Bundleless"](/en/guide/advance/in-depth-about-build#bundle- and-bundleless)
 
 ```tsx ./src/index.tsx
 import 'tailwindcss/utilities.css';
@@ -782,8 +782,8 @@ If you have special needs for the build product directory structure, you can use
 
 ## Testing components
 
-For more information on how to test components, please refer to [[Test project]](/en/guide/basic/test-your-project).
+For more information on how to test components, please refer to ["Test project"](/en/guide/basic/test-your-project).
 
 ## Releasing components
 
-It is recommended to use module project to provide version publishing function, you can refer to [[Versioning and publishing]](/en/guide/basic/publish-your-project).
+It is recommended to use module project to provide version publishing function, you can refer to ["Versioning and publishing"](/en/guide/basic/publish-your-project).

package/docs/en/guide/faq/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "FAQ",
+  "sidebar_position": 5
+}

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

@@ -0,0 +1,247 @@
+# Build FAQ
+
+## Product FAQ
+
+import BuildProductFAQ from '@site-docs-en/components/faq-build-product';
+
+<BuildProductFAQ/>
+
+### Initialization of Class Fields
+
+TypeSript provides the `useDefineForClassFields` configuration to control the conversion handling for `public class fields`.
+
+If we have a piece of code:
+
+``` ts
+class C {
+  foo = 100;
+  bar: string;
+}
+```
+
+When `useDefineForClassFields` is `false`, then the compiled code will look like:
+
+``` ts
+class C {
+  constructor() {
+    this.foo = 100;
+  }
+}
+```
+
+When `useDefineForClassFields` is `true`, then the compiled code will look like:
+
+``` ts
+class C {
+  constructor() {
+    Object.defineProperty(this, "foo", {
+      enumerable: true,
+      configurable: true,
+      writable: true,
+      value: 100,
+    });
+    Object.defineProperty(this, "bar", {
+      enumerable: true,
+      configurable: true,
+      writable: true,
+      value: void 0,
+    });
+  }
+}
+```
+
+Also the default value of this configuration will change depending on the [`target`](https://www.typescriptlang.org/tsconfig#target) configuration of tsconfig.json: When `target` is ES2022 or higher, then `useDefineForClassFields` is configured to `true` by default, otherwise it defaults to `false`.
+
+For more information on this configuration of TypeScript, you can refer to the following link:
+
+- [The useDefineForClassFields Flag and The declare Property Modifier](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#the-usedefineforclassfields-flag-and-the-declare-property-modifier)
+
+The Modern.js Module will currently process according to the following logic:
+
+1. The first decision to enable this feature inside Modern.js Module is based on the `useDefineForClassFields` configuration in tsconfig.json of the current project. Currently, only the contents of the tsconfig.json file under the current project path will be read, and the final tsconfig configuration based on the [`extends`](https://www.typescriptlang.org/tsconfig#extends) configuration is not supported at this time.
+2. If the `useDefineForClassFields` configuration of tsconfig.json is not detected, the default value is determined based on the `target` configuration of tsconfig.json. If `target` is greater than `ES2022` (including `EsNext`), then `useDefineForClassFields` defaults to `true`, otherwise it is `false`.
+3. If the `target` of tsconfig.json is not detected, it is processed according to the value of `useDefineForClassFields` as `true`.
+
+### babel-plugin-lodash treats the introduced lodash as `undefined`
+
+This problem occurs when using something like the following:
+
+``` ts
+import * as Lodash from 'lodash';
+
+export const libs = {
+  _: Lodash,
+}
+```
+
+Current related issues on the `babel-plugin-lodash` Github:
+
+- [#235](https://github.com/lodash/babel-plugin-lodash/issues/235)
+
+The solution to this problem is to remove `babel-plugin-lodash`, since the plugin is not needed for on-demand referencing at this point and using it would have side effects.
+
+A similar situation occurs with `babel-plugin-import`. If there is code like the following:
+
+``` ts
+import * as Comps from 'components';
+
+export const libs = {
+  comps: Comps,
+};
+```
+
+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.
+
+## Exceptions FAQ
+
+import BuildExceptionFAQ from '@site-docs-en/components/faq-build-exception';
+
+<BuildExceptionFAQ />
+
+### Dynamic require of "react" is not supported
+
+#### Problem Description
+
+When the product format in the product configuration of the build is ES modules.
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    format: 'esm',
+  },
+});
+```
+
+If you import a cjs product from a third-party npm package, the resulting product may not work properly under webpack.
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/shylnyhaeh7uldvivhn/1280X1280.png)
+
+#### Solution
+
+1. **First you need to find which third-party package is causing the problem**. For example, if the error message points to the `react` package, then look for a third-party package that has code like `require('react')` in it. For example [`react-draggable`](https://web-bnpm.byted.org/package/react-draggable), which only contains `cjs` products, then the problem is localized to the `react-draggable` package.
+2. Then we need to exclude this package with the following configuration, i.e. **not package problematic third-party packages**.
+
+``` ts
+export default defineConfig({
+  buildConfig: {
+    externals: ['react-draggable'],
+  }
+});
+```
+
+#### Reference Links
+
+- [When using esbuild with external react I get Dynamic require of "react" is not supported](https://stackoverflow.com/questions/68423950/when-using-esbuild-with-external-react-i-get-dynamic-require-of-react-is-not-s)
+
+### During compilation, an error was reported in the less file of a component library:`'Operation on an invalid type'`
+
+This is probably because the component library depends on Less version v3, while Modern.js Module defaults to v4. v3 and v4 have a Break Change in the `math` configuration, check this [link](https://stackoverflow.com/questions/73298187/less-error-operation-on-an-invalid-type-in-antd-dependency) for details.
+
+Therefore, if a component library like this is used in the source code:
+
+`buildPreset` is used in the build configuration, make the following changes:
+
+``` js
+module.exports = {
+  buildPreset({ extendPreset }) {
+    return extendPreset('your-build-preset', {
+      style: {
+        less: {
+          lessOptions: {
+            math: 'always',
+          },
+        },
+      },
+    });
+  },
+}
+```
+
+Or, if a custom `buildConfig` is used, modify it as follows:
+
+``` js
+module.exports = {
+  buildConfig: {
+    style: {
+      less: {
+        lessOptions: {
+          math: 'always',
+        },
+      },
+    },
+  }
+};
+```
+
+If you are using a component like this in Storybook, you will need to modify the debugging configuration of Storybook:
+
+```js
+module.exports = {
+  dev: {
+    storybook: {
+      webpackChain(chain, { CHAIN_ID }) {
+        chain.module
+          .rule(CHAIN_ID.RULE.LESS)
+          .use(CHAIN_ID.USE.LESS)
+          .tap(options => {
+            options.lessOptions = {
+              ...options.lessOptions,
+              math: 'always',
+            };
+            return options;
+          });
+      },
+    },
+  },
+}
+```
+
+### Bundle DTS failed
+
+Normally, the type file output with `tsc` is loose. Modern.js Module not only supports outputting loose type file products, but also supports packing type files, which allows you to package these loose type files and third-party dependent type files into one file.
+
+However, there is a risk in packaging the type files of third-party dependencies, **because there are cases where the type files of third-party dependencies cannot be packaged**.
+
+So when you encounter a `Bundle DTS failed` error message during the Modern.js Module build, you can observe that the error message comes from a third-party dependency. Try setting [`dts.respectExternal`](/api/config/build-config.html#dtsrespectexternal) to `false` to disable the behavior of packing type files of third-party dependencies.
+
+### Error reported for `defineConfig` function type: `If there is no reference to "..." then the inferred type of "default" cannot be named`
+
+Check if the [`include`](https://www.typescriptlang.org/tsconfig#include)  configuration exists in the project's tsconfig.json file, and if not, try adding the following:
+
+```json
+{
+  "include": ["src"]
+}
+```
+
+## Other FAQ
+
+import BuildOtherFAQ from '@site-docs-en/components/faq-build-other';
+
+<BuildOtherFAQ />
+
+### 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.
+
+The Modern.js Module provides [`esbuildOptions`](/api/config/build-config.html#esbuildoptions) configuration to allow modification of Modern.js's internal esbuild configuration, so that custom esbuild plugins can be added via this configuration:
+
+``` js
+export default defineConfig({
+  buildConfig: {
+    esbuildOptions: options => {
+      options.plugins = [
+        ...options.plugins,
+        yourEsbuildPlugin,
+      ];
+      return option;
+    },
+  },
+});
+```
+
+### Support for generating TypeScript declaration files for CSS Modules
+
+- First Solution: [typed-css-modules](https://github.com/Quramy/typed-css-modules)
+- Second Solution: [postcss-modules-dts](https://www.npmjs.com/package/@guanghechen/postcss-modules-dts)
+

package/docs/en/guide/faq/index.md

@@ -0,0 +1,7 @@
+# FAQ
+
+Here is a list of all frequently asked questions about Modern.js Module.
+
+- [Build FAQ](./build.mdx)
+- [Test FAQ](./test.mdx)
+- [Storybook FAQ](./storybook.mdx)

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

@@ -0,0 +1,102 @@
+# Storybook FAQ
+
+import BuildStorybookFAQ from '@site-docs-en/components/faq-storybook';
+
+<BuildStorybookFAQ />
+
+## Storybook v7 Support
+
+Storybook v7 does not support it yet. Rspack builds are currently planned to be supported in Storybook v7, so progress will be slower.
+
+Related Issue: [#3376](https://github.com/web-infra-dev/modern.js/issues/3376).
+
+## Using Storybook Addon or other configurations does not work
+
+Modern.js Module is currently using Storybook version v6, if you are using Addon version v7 you may not be able to get the addon to work.
+
+In addition to the Addon, other configurations may also have differences. For example, if you modify the `preview.js` configuration file, Storybook v6 is written differently than v7:
+
+- v6：[Document](https://storybook.js.org/docs/6.5/react/writing-stories/decorators#global-decorators)
+- v7：[Document](https://storybook.js.org/docs/react/writing-stories/decorators#global-decorators)
+
+## Cannot find module 'react-dom/package.json
+
+When debug Storybook, the following problem occurs:
+
+```bash
+ERR! Error: Cannot find module 'react-dom/package.json'
+```
+
+You can install the react-dom dependency in the project.
+
+``` json
+{
+    "devDependencies": {
+        "react-dom": "^17"
+    }
+}
+```
+
+## Unable to locate the specific error message
+
+Solutions:
+
+1. Find `@storybook/core-server/dist/cjs/dev-server.js`
+2. Find this code: `var _await$Promise$all = await Promise.all([preview, manager,`.
+3. Modify it：
+
+``` js
+var _await$Promise$all = await Promise.all([
+    preview.catch(e => console.info(e)),
+    manager // TODO #13083 Restore this when compiling the preview is fast enough
+  // .then((result) => {
+  //   if (!options.ci && !options.smokeTest) openInBrowser(address);
+  //   return result;
+  // })
+  .catch(previewBuilder.bail)]),
+      _await$Promise$all2 = _slicedToArray(_await$Promise$all, 2),
+      previewResult = _await$Promise$all2[0],
+      managerResult = _await$Promise$all2[1]; // TODO #13083 Remove this when compiling the preview is fast enough
+```
+
+## Can`t find any stories is your Storybook
+
+![storybook-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/shylnyhaeh7uldvivhn/01719a11-1939-4009-9317-5e2b491ae52f.png)
+
+When you get a problem like this, you can first open the browser console and there should be some error messages. You can use the error messages to deduce if there is a problem in the code you are writing that is causing Storybook to not work properly.
+
+## Storybook Adds Proxy Functionality
+
+Storybook does not provide a solution for this, but there is one in the Storybook Issue. In the Modern.js Module, you can:
+
+1. Add the `config/storybook/middleware.js` file and initialize the following:
+
+``` js
+/* eslint-disable filenames/match-exported */
+module.exports = function expressMiddleware(router) {
+    // router is express router
+    // import { Router } from 'express'
+    // router = new Router();
+};
+```
+
+2. add `http-proxy-middleware` dependency
+3. Add proxy routing-related configuration
+
+``` js
+/* eslint-disable filenames/match-exported */
+const { createProxyMiddleware } = require("http-proxy-middleware");
+
+module.exports = function expressMiddleware (router) {
+  router.use('/api', createProxyMiddleware({
+    target: "http://localhost:8000",
+    changeOrigin: true
+  }))
+}
+```
+
+Link：https://github.com/storybookjs/storybook/issues/11551
+
+## Modify the directory where the Story file exists
+
+The directory where Story files are stored cannot be modified at the moment, only the `*.stories.(t|j)s(x)` and `*.stories.md(x)` files in the `your-project/stories` directory are recognized as Story files.

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

@@ -0,0 +1,11 @@
+# Test FAQ
+
+import TestFAQ from '@site-docs-en/components/faq-test';
+
+<TestFAQ />
+
+### Execute `test` command with an error `TypeError: Cannot read property 'testEnvironmentOptions' of undefined`
+
+![jest-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/shylnyhaeh7uldvivhn/jest-error-testEnvironmentOptions-of-undefined.jpeg)
+
+You can check whether other projects in Monorepo have `jest-environment-jsdom` dependencies and unify them with the overrides provided by Monorepo.

package/docs/en/plugins/guide/setup-function.mdx

@@ -4,7 +4,7 @@ sidebar_position: 3
 
 # Setup function
 
-In the [[Plugin object]](/plugins/guide/plugin-object) section we know that the plug-in object contains a `setup` function that not only contains an `api` object parameter, but also returns a Hooks object.
+In the ["Plugin object"](/plugins/guide/plugin-object) section we know that the plug-in object contains a `setup` function that not only contains an `api` object parameter, but also returns a Hooks object.
 
 ## Plugin API objects
 

package/docs/en/plugins/official-list/plugin-banner.md

@@ -39,7 +39,7 @@ export default defineConfig({
 ```
 
 :::tip
-Note: CSS comments do not support the `//comment` syntax. Refer to [【CSS Comments】](https://developer.mozilla.org/en-US/docs/Web/CSS/Comments)
+Note: CSS comments do not support the `//comment` syntax. Refer to ["CSS Comments"](https://developer.mozilla.org/en-US/docs/Web/CSS/Comments)
 :::
 
 ## Example

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

@@ -3,7 +3,7 @@
 Using [SWC](https://swc.rs/) provides the same ability and configuration as [`babel-plugin-import`](https://github.com/umijs/babel-plugin-import).
 
 :::tip
-Since @modern-js/module-tools version >= 2.16.0, this plugin functionality is built into module-tools and is provided by [`transformImport`](api/config/build-config.html#transformimport).
+Since `@modern-js/module-tools` version >= v2.16.0, this plugin functionality is built into Module Tools and is provided by [`transformImport`](api/config/build-config.html#transformimport).
 :::
 
 ## Quick Start
@@ -26,17 +26,19 @@ pnpm add @modern-js/plugin-module-import -D
 In Module Tools, you can register plugins in the following way:
 
 ```ts
-import { moduleTools, defineConfig  } from '@modern-js/module-tools';
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { modulePluginImport } from '@modern-js/plugin-module-import';
 
 export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'antd',
-        style: true,
-      }],
+      pluginImport: [
+        {
+          libraryName: 'antd',
+          style: true,
+        },
+      ],
     }),
   ],
 });
@@ -46,17 +48,17 @@ This way we can use the ability of automatic import in Module Tools.
 
 ## Configurations
 
-* **Type**:
+- **Type**:
 
 ```ts
 type Options = {
   pluginImport?: ImportItem[];
-}
+};
 ```
 
 ### pluginImport
 
-* **Type**: `Array`
+- **Type**: `object[]`
 
 The elements of the array are configuration objects for `babel-plugin-import`, which can be referred to [options](https://github.com/umijs/babel-plugin-import#options)。
 
@@ -64,7 +66,7 @@ The elements of the array are configuration objects for `babel-plugin-import`, w
 
 ```ts
 import { modulePluginImport } from '@modern-js/plugin-module-import';
-import { moduleTools, defineConfig  } from '@modern-js/module-tools';
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
   plugins: [
@@ -75,7 +77,7 @@ export default defineConfig({
         {
           libraryName: 'foo',
           style: true,
-        }
+        },
       ],
     }),
   ],
@@ -110,16 +112,18 @@ Add the following configuration on the right-hand side:
 
 ```ts
 import { modulePluginImport } from '@modern-js/plugin-module-import';
-import { moduleTools, defineConfig  } from '@modern-js/module-tools';
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'foo',
-        customName: 'foo/es/{{ member }}'
-      }],
+      pluginImport: [
+        {
+          libraryName: 'foo',
+          customName: 'foo/es/{{ member }}',
+        },
+      ],
     }),
   ],
 });
@@ -135,16 +139,19 @@ import { modulePluginImport } from '@modern-js/plugin-module-import';
 export default defineConfig({
   plugins: [
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'foo',
-        customName: 'foo/es/{{ member }}'
-      }],
+      pluginImport: [
+        {
+          libraryName: 'foo',
+          customName: 'foo/es/{{ member }}',
+        },
+      ],
     }),
   ],
 });
 ```
 
 ---
+
 After transformation:
 
 ```ts
@@ -159,16 +166,18 @@ The template used here is [handlebars](https://handlebarsjs.com). There are some
 
 ```ts focus=8:8
 import { modulePluginImport } from '@modern-js/plugin-module-import';
-import { moduleTools, defineConfig  } from '@modern-js/module-tools';
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
   plugins: [
     moduleTools(),
     modulePluginImport({
-      pluginImport: [{
-        libraryName: 'foo',
-        customName: 'foo/es/{{ kebabCase member }}',
-      }],
+      pluginImport: [
+        {
+          libraryName: 'foo',
+          customName: 'foo/es/{{ kebabCase member }}',
+        },
+      ],
     }),
   ],
 });