@modern-js/module-tools-docs 2.32.1 → 2.33.0

package/docs/en/guide/basic/modify-output-product.md

@@ -23,7 +23,7 @@ export default defineConfig({
 
 **The default output files has the following characteristics**.
 
-- will generate [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) and [ESM](https://nodejs.org/api/esm.html#modules- ecmascript-modules).
+- will generate [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) and [ESM](https://nodejs.org/api/esm.html#modules-ecmascript-modules).
 - The code syntax is supported up to `ES6` , and more advanced syntax will be converted.
 - All code is bundled into one file, i.e. **bundle** processing is performed.
 - The output root directory is the `dist` directory under the project, and the type file output directory is `dist/types`.
@@ -37,62 +37,18 @@ Then the next step is to first explain `buildPreset`.
 
 ## buildPreset
 
-The `buildPreset` represents one or more sets of build-related configurations prepared in advance. By using the corresponding preset values of the `buildPreset`, you can eliminate the troublesome and complicated configuration work and get the expected product.
+The `buildPreset` represents a prepared set or sets of build-related configurations that can be used to eliminate the trouble and complexity of configuration by using the default values corresponding to the build Preset, resulting in the expected product.
 
-### String form of build preset
+Module Tools mainly comes with two built-in build presets, including:
 
-The value of a **build preset can be in the form of a string**, so a build preset of this form is called a preset string.
+- npm-component: Used to build component libraries.
+- npm-library: Used to package projects of other library types, such as tool libraries.
 
-The Module Tools provides generic build preset strings and corresponding variants, depending on the generic scenario in which the npm package is used. All currently supported preset strings can be viewed via the [BuildPreset API](/api/config/build-preset). Here is an explanation about the relationship between **generic preset strings and variants**.
+It also provides some variations, such as `npm-library-with-umd` and `npm-library-es5`, which, as their names suggest, correspond to library presets with umd output and support for es5 syntax, respectively. For more detailed configuration, you can refer to its [API](/api/config/build-preset).
 
-Among the generic preset strings, `"npm-library"` can be used in the scenario of developing npm packages of the library type, which is suitable for most common module type projects. When `"npm-library"` is set, the output files of the project will have the following characteristics.
+In addition, we can also fully customize the build configuration:
 
-- In the `dist/lib` directory you will get code formatted as `cjs`, syntax supported up to `es6` and bundled.
-- In the `dist/es` directory, you get code in the format `esm`, with syntax support up to `es6` and after bundling.
-- In the `dist/types` directory, you get the type files. If it is not a TypeScript project, there is no such directory.
-
-The default string `"npm-library"` is a variant of the original product with a modified **code syntax support** feature and a string naming change to `"npm-library-[es5 | es2016.... . es2020 | esnext]"`.
-
-For example, if the output file is based on the preset string `"npm-library"` and the syntax supported by the output code is changed to `es5`, then simply changing `"npm-library"` to `"npm-library-es5"` would be sufficient.
-
-### Build pre-defined function forms
-
-**In addition to the string form, the value of a build preset can also be in the form of a function, where the specific configuration corresponding to a preset value can be printed or modified**.
-
-For example, to achieve the same effect as the preset string ``npm-library-es5"` using the form of a preset function, you can do the following.
-
-```ts title="modern.config.ts"
-import { moduleTools, defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  plugins: [moduleTools()],
-  buildPreset({ preset }) {
-    return preset.NPM_LIBRARY.map(config => {
-      return { ... .config, target: 'es5' }
-    });
-  },
-});
-```
-
-In the above code implementation, `preset.NPM_LIBRARY` corresponds to the preset string `"npm-library"`, representing multiple build-related configurations equivalent to `"npm-library"`.
-
-We use the `map` method to iterate over the `NPM_LIBRARY` array, which contains multiple `buildConfig` objects. We perform a shallow copy of the original `buildConfig` object and modify the value of the `target` property in the shallow copy to be `es5`.
-
-If you want to know the specific contents included in `preset.NPM_LIBRARY`, you can refer to the [BuildPreset API](/api/config/build-preset).
-
-In addition, under the `preset` object, it not only includes `NPM_LIBRARY`, but also other similar constants.
-
-> NPM_LIBRARY`, you can check it with [BuildPreset API](/api/config/build-preset). The`preset`object contains not only`NPM_LIBRARY`, but also other similar constants.
-
-:::tip
-We can not only use `preset.NPM_LIBRARY`to get the build configuration corresponding to`"npm-library"`, but also `preset['npm-library']` in this way.
-:::
-
-So what is the `buildConfig` object here? What is the basis for the build artifacts feature mentioned before?
-
-Let's explain next.
-
-## Build configuration (object)
+## buildConfig
 
 **`buildConfig` is a configuration option that describes how to compile and generate build artifacts**. What was mentioned at the beginning about "_features of build products_" are actually properties supported by `buildConfig`. The currently supported properties cover the needs of most module type projects when building products. `buildConfig` not only contains some properties that artifacts have, but also contains some features needed to build products. The following is a brief list from a classification point of view.
 
@@ -129,36 +85,54 @@ Let's explain next.
 
 In addition to the above categories, frequently asked questions and best practices about these APIs can be found at the following links
 
-- [What are `bundle` and `bundleless`?](/guide/advance/in-depth-about-build#bundle- and-bundleless)
-- [Relationship of `input` to `sourceDir`](/guide/advance/in-depth-about-build#input- to -sourcedir-)
-- [Multiple ways to generate type files in product](/guide/advance/in-depth-about-build#type-files).
-- [`buildConfig.define` Different ways to use it for different scenarios.](/guide/advance/in-depth-about-build#buildconfigdefine - How to use it for different scenarios)
+- [About `bundle` and `bundleless`?](/guide/advance/in-depth-about-build#bundle--bundleless)
+- [About `input` and `sourceDir`](/guide/advance/in-depth-about-build#input--sourcedir)
+- [About d.ts](/guide/advance/in-depth-about-build#dts).
+- [How to use define](/guide/advance/in-depth-about-build#define)
 - [How to handle third-party dependencies?](/guide/advance/external-dependency)
 - [How to use copy?](/guide/advance/copy)
-- How do I build umd artifacts? (/guide/advance/build-umd# sets the global variable name of the project)
-- [The capabilities currently supported by static resources.](/guide/advance/asset)
+- [How to use umd](/guide/advance/build-umd)
+- [How to use asset](/guide/advance/asset)
+
+## Combining Configuration and Presets
+
+Once we understand `buildPreset` and `buildConfig`, we can use them together.
 
-## When to use `buildConfig`
+In a real project, we can use `buildPreset` to quickly get a set of default build configurations. If you need to customise it, you can use `buildConfig` to override and extend it.
 
-`buildConfig` is one of the methods used to modify the product, **only `buildConfig` will take effect when configured in conjunction with `buildPreset`**. So if configured as follows.
+The extension logic is as follows.
+
+- When `buildConfig` is an array, new configuration items are added to the original preset.
 
 ```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/module-tools';
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({
-  buildConfig: {
-    format: 'umd',
-  },
+  plugins: [moduleTools()],
   buildPreset: 'npm-library',
+  buildConfig: [
+    {
+      format: 'iife',
+      target: 'es2020',
+      outDir: '. /dist/global'
+    }
+  ]
 });
 ```
 
-Then at this point you will see the following prompt.
+This will generate an additional IIFE-formatted product that supports up to ES2020 syntax on top of the original preset, in the `dist/global` directory under the project.
 
-```bash
-Since both 'buildConfig' and 'buildPreset' are present, only the 'buildConfig' configuration will take effect
-```
+- When `buildConfig` is an object, the configuration items in the object are overwritten in the preset.
 
-The set or sets of build-related configurations represented by `buildPreset` are composed of `buildConfig`, **which can be used to customize output products** when the current project needs cannot be met using `buildPreset`.
+```ts title="modern.config.ts"
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
+export default defineConfig({
+  plugins: [moduleTools()],
+  buildPreset: 'npm-library',
+  buildConfig: {
+    sourceMap: true,
+  },
+}).
+```
 
-The process of using `buildConfig` is the process of thinking about **what kind of build artifacts to get**.
+This will cause a sourceMap file to be generated for each build task.

package/docs/en/guide/basic/test-your-project.mdx

@@ -79,8 +79,6 @@ npm run test
 
 ### Components
 
-{/* 链接待补充 */}
-
 For components, Modern.js's Runtime API provides functionality for testing UI components, which is provided by `@modern-js/runtime/testing`.
 
 :::tip

package/docs/en/guide/basic/use-micro-generator.md

@@ -18,20 +18,18 @@ The microgenerator can be started via [`modern new`](/guide/basic/command-previe
 
 When we want to test some modules, we can enable the test feature. When this feature is enabled, **a `tests` directory and related files will be created in the project directory, and a new `"@modern-js/plugin-testing"` dependency will be added to package.json**.
 
-
 :::tip
 After successfully enabling it, you will be prompted to manually add a code similar to the one below to the configuration.
+
 ```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { testingPlugin } from '@modern-js/plugin-testing';
 
 export default defineConfig({
-  plugins: [
-    moduleTools(),
-    testingPlugin(),
-  ],
+  plugins: [moduleTools(), testingPlugin()],
 });
 ```
+
 :::
 
 ## Storybook
@@ -40,17 +38,16 @@ The **Storybook feature** can be enabled when we want to debug a component or a
 
 :::tip
 After successfully enabling it, you will be prompted to manually add a code similar to the one below to the configuration.
+
 ```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import { storybookPlugin } from '@modern-js/plugin-storybook';
 
 export default defineConfig({
-  plugins: [
-    moduleTools(),
-    storybookPlugin(),
-  ],
+  plugins: [moduleTools(), storybookPlugin()],
 });
 ```
+
 :::
 
 For more information on how to start Storybook and how to use it, check out the following link.
@@ -58,50 +55,28 @@ For more information on how to start Storybook and how to use it, check out the
 - [`modern dev`](/en/guide/basic/command-preview#modern-dev)
 - [`using Storybook`](/en/guide/basic/using-storybook)
 
-## Tailwind CSS support
+## Tailwind CSS Support
 
-This can be enabled when we want to add [Tailwind CSS](https://v2.tailwindcss.com/) support to our project. Tailwind CSS is a CSS library that provides out-of-the-box styling.
-
-For more information on how to use Tailwind CSS in your module projects, check out.
-
-<!-- 链接待补充 -->
-
-- Using Tailwind CSS
-
-:::tip
-After successfully enabling it, you will be prompted to manually add a code similar to the one below to the configuration.
-```ts
-import { moduleTools, defineConfig } from '@modern-js/module-tools';
-import { tailwindcssPlugin } from '@modern-js/plugin-tailwindcss';
+[Tailwind CSS](https://tailwindcss.com/) is a CSS framework and design system based on Utility Class, which can quickly add common styles to components, and support flexible extension of theme styles.
 
-export default defineConfig({
-  plugins: [
-    moduleTools(),
-    tailwindPlugin(),
-  ],
-});
-```
-:::
+If you want to use Tailwind CSS for a project, you can refer to ["Using Tailwind CSS"](https://modernjs.dev/module-tools/guide/best-practices/components.html#tailwind-css).
 
 ## Modern.js Runtime API
 
-<!-- 链接待补充 -->
-
 **Modern.js provides Runtime API capabilities that can only be used in the Modern.js application project environment**. If you need to develop a component for use in a Modern.js application environment, then you can turn on this feature and the microgenerator will add the `"@modern-js/runtime"` dependency.
 
 Also, the Storybook debugging tool will determine if the project needs to use the Runtime API by checking the project's dependencies and providing the same Runtime API runtime environment as the Modern.js application project.
 
 :::tip
 After successfully enabling it, you will be prompted to manually add a code similar to the one below to the configuration.
+
 ```ts
 import { moduleTools, defineConfig } from '@modern-js/module-tools';
 import runtime from '@modern-js/runtime/cli';
 
 export default defineConfig({
-  plugins: [
-    moduleTools(),
-    runtime(),
-  ],
+  plugins: [moduleTools(), runtime()],
 });
 ```
+
 :::

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

@@ -166,3 +166,18 @@ For the `modern build --platform` command you can see.
 - [`modern build`](/en/guide/basic/command-preview#modern-build)
 
 After the build is complete, you can see the build artifacts files in the `dist/storybook-static` directory.
+
+## Use Tailwind CSS with Storybook
+
+If you need to use Tailwind CSS in the `stories` directory, make sure that the Tailwind CSS configuration for your current project includes the `stories` directory.
+
+Taking the `tailwind.config.ts` file as an example, you need to configure the following content:
+
+```diff title="tailwind.config.ts"
+export default {
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
++   './stories/**/*.{js,jsx,ts,tsx}',
+  ],
+};
+```

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

@@ -1,3 +1,7 @@
+---
+sidebar_position: 1
+---
+
 # Developing Components
 
 This chapter will describe how to develop component projects using the Module Tools.
@@ -164,204 +168,7 @@ body {
 
 ### Tailwind CSS
 
-The module project supports the development of component styles using Tailwind CSS.
-
-By default, this feature is not enabled in the module project, you need to enable it as follows.
-
-1. The Tailwind CSS feature can be enabled by executing the `new` command in the project root directory.
-
-```text title="Terminal"
-pnpm run new
-
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable Tailwind CSS
-```
-
-2. Once successfully enabled, you will see that a new dependency has been added to `package.json`.
-
-```json title="./package.json"
-{
-  "devDependencies": {
-    "@modern-js/plugin-tailwindcss": "x.y.z"
-  }
-}
-```
-
-3. Tailwind CSS offers two ways to use it.
-
-#### HTML class
-
-Tailwind CSS supports adding styles to HTML tags by using class names. **When using HTML class names, be sure to import the Tailwind CSS equivalent css file. **
-
-```tsx title="./src/index.tsx"
-import 'tailwindcss/utilities.css';
-
-export default () => {
-  return <div className="bg-black text-white">hello world</div>;
-};
-```
-
-Style product (This is a bundle build):
-
-```css title="./dist/es/index.css"
-/* node_modules/tailwindcss/utilities.css */
-.table {
-  display: table;
-}
-.bg-black {
-  --tw-bg-opacity: 1;
-  background-color: rgba(0, 0, 0, var(--tw-bg-opacity));
-}
-.text-white {
-  --tw-text-opacity: 1;
-  color: rgba(255, 255, 255, var(--tw-text-opacity));
-}
-/** some more... */
-```
-
-#### `@apply`
-
-Tailwind CSS provides the [`@apply`](https://v2.tailwindcss.com/docs/functions-and-directives#apply) directive, which allows us to inline the styles provided by Tailwind CSS into the styles we write.
-
-`@apply` can be used in CSS, Less, and Sass.
-
-```css
-.btn {
-  @apply font-bold py-2 px-4 rounded;
-}
-```
-
-However, there are some things to keep in mind when using Less and Sass.
-
-##### Sass
-
-When using Tailwind with Sass, the presence of `!important` after `@apply` requires interpolation to get Sass to compile correctly.
-
-- It does not work properly:
-
-```sass
-.alert {
-  @apply bg-red-500 !important;
-}
-```
-
-- Can work properly:
-
-```sass
-.alert {
-  @apply bg-red-500 #{!important};
-}
-```
-
-##### Less
-
-When using Tailwind with Less, you cannot nest Tailwind's `@screen` directive.
-
-- It does not work properly:
-
-```less
-.card {
-  @apply rounded-none;
-
-  @screen sm {
-    @apply rounded-lg;
-  }
-}
-```
-
-- Instead, use regular media queries and the `theme()` function to reference your screen size, or simply don't nest your `@screen` directive.
-
-```less title="Method One"
-// Use a regular media query and theme()
-.card {
-  @apply rounded-none;
-
-  @media (min-width: theme('screens.sm')) {
-    @apply rounded-lg;
-  }
-}
-```
-
-```less title="Method Two"
-// Use the @screen directive at the top-level
-.card {
-  @apply rounded-none;
-
-  @media (min-width: theme('screens.sm')) {
-    @apply rounded-lg;
-  }
-}
-```
-
-#### Recommended method
-
-**It is recommended to develop styles in the way specified by `@apply`, so that only styles inlined by directives are included in the style product. **
-
-When adding styles using HTML class names, by default Tailwind will not only add the styles corresponding to its own class name to the product, but will also have additional style code that may not affect its own styles.
-
-#### The difference between bundle and bundleless build products
-
-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)
-
-```tsx title="./src/index.tsx"
-import 'tailwindcss/utilities.css';
-
-export default () => {
-  return <div className="bg-black text-white">hello world11</div>;
-};
-```
-
-In Bundle mode, third-party dependencies are bundled in.
-
-For styles, a separate output file is generated, and there is no code related to importing styles in the JS output files.
-
-If you need to inject styles into JS output files, you can enable the [`style.inject`](/en/api/config/build-config#styleinject) option.
-
-```css title="./dist/es/index.css"
-/* node_modules/tailwindcss/utilities.css */
-.table {
-  display: table;
-}
-.bg-black {
-  --tw-bg-opacity: 1;
-  background-color: rgba(0, 0, 0, var(--tw-bg-opacity));
-}
-.text-white {
-  --tw-text-opacity: 1;
-  color: rgba(255, 255, 255, var(--tw-text-opacity));
-}
-/** some more... */
-```
-
-``` js ./dist/es/index.js
-// src/index.tsx
-import { jsx } from "react/jsx-runtime";
-var src_default = () => {
-  return /* @__PURE__ */ jsx("div", {
-    className: "bg-black text-white",
-    children: "hello world11"
-  });
-};
-export {
-  src_default as default
-};
-```
-
-In Bundleless mode, no third-party dependencies are bundled, and no style artifacts are generated at this time.
-
-```js title="./dist/es/index.js"
-import { jsx } from 'react/jsx-runtime';
-import 'tailwindcss/utilities.css';
-var src_default = () => {
-  return /* @__PURE__ */ jsx('div', {
-    className: 'bg-black text-white',
-    children: 'hello world11',
-  });
-};
-export { src_default as default };
-```
+Please refer to ["Using Tailwind CSS"](/guide/best-practices/use-tailwindcss.html) for detailed usage.
 
 ### CSS Modules