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

package/docs/en/guide/best-practices/use-tailwindcss.mdx

@@ -0,0 +1,289 @@
+---
+sidebar_position: 2
+---
+
+# Using Tailwind CSS
+
+[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.
+
+Module Tools supports developing component styles using Tailwind CSS.
+
+## Enabling Tailwind CSS
+
+By default, Module Tools does not have this feature enabled. You can enable it by following the steps below.
+
+1. Execute the `new` command in the project root directory to enable Tailwind CSS.
+
+```text title="Terminal"
+pnpm run new
+
+? Please select the operation you want: Enable features
+? Please select the feature name: Enable Tailwind CSS
+```
+
+2. After successful enabling, you will see a new dependency added to `package.json`.
+
+```json title="./package.json"
+{
+  "devDependencies": {
+    "@modern-js/plugin-tailwindcss": "x.y.z"
+  }
+}
+```
+
+3. Finally, you need to manually register the `tailwindcssPlugin` in the configuration file:
+
+```ts title="modern.config.ts"
+import { moduleTools, defineConfig } from '@modern-js/module-tools';
+import { tailwindcssPlugin } from '@modern-js/plugin-tailwindcss';
+
+export default defineConfig({
+  plugins: [moduleTools(), tailwindPlugin()],
+});
+```
+
+## Configuring Tailwind CSS
+
+In Module Tools, you have two ways to configure Tailwind CSS:
+
+1. Using the `tailwind.config.{ts,js}` file, which follows the official usage of Tailwind CSS. Please refer to ["Tailwind CSS - Configuration"](https://tailwindcss.com/docs/configuration) for more details.
+
+```ts title="tailwind.config.ts"
+import type { Config } from 'tailwindcss';
+
+export default {
+  content: ['./src/**/*.{js,jsx,ts,tsx}'],
+} as Config;
+```
+
+:::tip
+Please upgrade Modern.js to version >= MAJOR_VERSION.33.0 to support automatic reading of `tailwind.config.{ts,js}` files.
+:::
+
+2. Using the [style.tailwindcss](/api/config/build-config.html#styletailwindcss) configuration option. This is the old way of configuring Tailwind CSS, and we recommend using the `tailwind.config.{ts,js}` file for configuration.
+
+```ts title="modern.config.ts"
+export default {
+  tools: {
+    tailwindcss: {
+      content: ['./src/**/*.{js,jsx,ts,tsx}'],
+    },
+  },
+};
+```
+
+If you are using both the `tailwind.config.{ts,js}` file and `style.tailwindcss` option, the configuration defined in `style.tailwindcss` will take precedence and override the content defined in `tailwind.config.{ts,js}`.
+
+### Tailwind CSS Autocomplete
+
+Tailwind CSS provides an official extension called [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) for autocompletion of Tailwind CSS class names, CSS functions, and directives in VS Code.
+
+You can follow the steps below to enable the autocomplete feature:
+
+1. Install the [Tailwind CSS IntelliSense](https://github.com/tailwindlabs/tailwindcss-intellisense) extension in VS Code.
+2. If the root directory of your project does not have a `tailwind.config.{ts,js}` file, you need to create one and write the Tailwind CSS configuration for your current project. Otherwise, the IDE plugin will not work correctly.
+
+## Usage Introduction
+
+Tailwind CSS provides two ways of usage:
+
+### HTML Class Names
+
+Tailwind CSS supports adding styles by using class names on HTML tags. **When using HTML class names, make sure to import the corresponding CSS file of Tailwind CSS.**
+
+```tsx title="./src/index.tsx"
+import 'tailwindcss/utilities.css';
+
+export default () => {
+  return <div className="bg-black text-white">hello world</div>;
+};
+```
+
+Generated styles (after bundling):
+
+```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 our own styles.
+
+`@apply` can be used in CSS, Less, and Sass.
+
+```css
+.btn {
+  @apply font-bold py-2 px-4 rounded;
+}
+```
+
+However, there are some considerations when using it with Less and Sass:
+
+#### Sass
+
+When using Tailwind with Sass and there is an `!important` after `@apply`, interpolation should be used to ensure Sass compiles correctly.
+
+- Won't work as expected:
+
+```sass
+.alert {
+  @apply bg-red-500 !important;
+}
+```
+
+- Will work as expected:
+
+```sass
+.alert {
+  @apply bg-red-500 #{!important};
+}
+```
+
+#### Less
+
+When using Tailwind with Less, you cannot nest Tailwind's `@screen` directive.
+
+- Won't work as expected:
+
+```less
+.card {
+  @apply rounded-none;
+
+  @screen sm {
+    @apply rounded-lg;
+  }
+}
+```
+
+- Instead, use regular media queries and the `theme()` function to reference your screen sizes or simply avoid nesting your `@screen` directive.
+
+```less title="Method 1"
+// Use a regular media query and theme()
+.card {
+  @apply rounded-none;
+
+  @media (min-width: theme('screens.sm')) {
+    @apply rounded-lg;
+  }
+}
+```
+
+```less title="Method 2"
+// Use the @screen directive at the top-level
+.card {
+  @apply rounded-none;
+
+  @media (min-width: theme('screens.sm')) {
+    @apply rounded-lg;
+  }
+}
+```
+
+### Recommended Approach
+
+**It is recommended to develop styles using the `@apply` directive so that the resulting styles only include the inline styles specified by the directive.**
+
+When adding styles using HTML class names, by default, Tailwind includes not only the styles corresponding to the class names but also additional style code. Although these additional code may not affect the styles themselves.
+
+### Difference between Bundle and Bundleless Builds
+
+For the following code, there is a significant difference in the build output between bundle and bundleless modes.
+
+> For more information about bundle and bundleless, refer to [Bundle and Bundleless](/guide/advance/in-depth-about-build#bundle--bundleless)
+
+```tsx title="./src/index.tsx"
+import 'tailwindcss/utilities.css';
+
+export default () => {
+  return <div className="bg-black text-white">hello world11</div>;
+};
+```
+
+In the Bundle mode, third-party dependencies are bundled together.
+
+For styles, a separate output file is generated, and there is no import code related to styles in the JS output file.
+
+To inject styles into the JS output, you can enable the [`style.inject`](/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 title="./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, third-party dependencies are not bundled together, and no style artifacts will be generated.
+
+```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 };
+```
+
+### About `designSystem` config
+
+`designSystem` is a deprecated configuration option in Module Tools.
+
+Starting from Module Tools vMAJOR_VERSION.33.0, you can use the `theme` configuration option of Tailwind CSS as a replacement for `designSystem`. It is no longer necessary to split the `theme` configuration and set it on `designSystem`.
+
+- Previous usage:
+
+```ts title="modern.config.ts"
+const { theme, ...rest } = tailwindConfig;
+
+export default {
+  style: {
+    tailwindcss: rest,
+  },
+  designSystem: theme,
+};
+```
+
+- Current usage:
+
+```ts title="modern.config.ts"
+export default {
+  style: {
+    tailwindcss: tailwindConfig,
+  },
+};
+```

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

@@ -63,7 +63,6 @@ const useResolvedConfigContext: () => NormalizedConfig;
 interface NormalizedConfig {
   buildConfig: PartialBuildConfig;
   buildPreset: BuildPreset;
-  designSystem?: Record<string, any>;
   dev: Dev;
   plugins: PluginConfig;
   runtime: RuntimeConfig;

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

@@ -7,7 +7,6 @@ sidebar_position: 1
 `buildConfig` 是一个用来描述如何编译、生成构建产物的配置项，它包含了构建的所有配置。
 
 - 类型：`object | object[]`
-- 默认值: `undefined`
 
 :::tip
 在开始使用 `buildConfig` 之前，请先阅读以下文档来了解其作用：
@@ -521,7 +520,7 @@ export default defineConfig({
 - 类型：`'esm' | 'cjs' | 'iife' | 'umd'`
 - 默认值：`cjs`
 
-### format: 'esm'
+### format: esm
 
 esm 代表 "ECMAScript 模块"，它需要运行环境支持 import 和 export 语法。
 
@@ -535,7 +534,7 @@ export default defineConfig({
 });
 ```
 
-### format: 'cjs'
+### format: cjs
 
 cjs 代表 "CommonJS"，它需要运行环境支持 exports、require 和 module 语法，通常为 Node.js 环境。
 
@@ -549,7 +548,7 @@ export default defineConfig({
 });
 ```
 
-### format: 'iife'
+### format: iife
 
 iife 代表 "立即调用函数表达式"，它将代码包裹在函数表达式中，确保代码中的任何变量不会意外地与全局范围中的变量冲突，通常在浏览器环境中运行。
 
@@ -563,7 +562,7 @@ export default defineConfig({
 });
 ```
 
-### format: 'umd'
+### format: umd
 
 umd 代表 "Universal Module Definition"，用于在不同环境（浏览器、Node.js 等）中运行。umd 格式的模块可以在多种环境下使用，既可以作为全局变量访问，也可以通过模块加载器（如 RequireJS）进行模块化加载。
 
@@ -1086,13 +1085,10 @@ export default defineConfig({
 
 ## style.tailwindcss
 
-Tailwind CSS 相关配置。
+用于修改 [Tailwind CSS](https://tailwindcss.com/docs/configuration) 的配置项。
 
 - 类型： `object | Function`
-- 默认值： `见下方配置详情`
-
-<details>
-  <summary>Tailwind CSS 配置详情</summary>
+- 默认值：
 
 ```js title="modern.config.ts"
 const tailwind = {
@@ -1104,7 +1100,13 @@ const tailwind = {
 };
 ```
 
-</details>
+### 启用 Tailwind CSS
+
+在使用 `style.tailwindcss` 之前，你需要启用 Module Tools 的 Tailwind CSS 插件。
+
+请阅读[「使用 Tailwind CSS」](/guide/best-practices/use-tailwindcss.html) 章节来了解开启方式。
+
+### 类型
 
 值为 `object` 类型时，与默认配置通过 `Object.assign` 合并。
 
@@ -1114,7 +1116,10 @@ const tailwind = {
 
 ### 注意事项
 
-注意，如果你同时使用了 [designSystem](/api/config/design-system) 配置项，那么 Tailwind CSS 的 `theme` 配置将会被 `designSystem` 的值所覆盖。
+注意：
+
+- 如果你同时使用了 `tailwind.config.{ts,js}` 文件和 `tools.tailwindcss` 选项，那么 `tools.tailwindcss` 定义的配置会优先生效，并覆盖 `tailwind.config.{ts,js}` 中定义的内容。
+- 如果你同时使用了 `designSystem` 配置项，那么 Tailwind CSS 的 `theme` 配置将会被 `designSystem` 的值所覆盖。
 
 其他配置的使用方式与 Tailwind CSS 官方用法一致，请参考 [tailwindcss - Configuration](https://tailwindcss.com/docs/configuration)。
 
@@ -1176,8 +1181,6 @@ export default defineConfig({
 });
 ```
 
-### 注意事项
-
 参考[「Import 插件——注意事项」](plugins/official-list/plugin-import.html#注意事项)
 
 ## transformLodash
@@ -1187,13 +1190,11 @@ export default defineConfig({
 - 类型：`boolean`
 - 默认值：`true`
 
-### 示例
-
 该选项默认开启，Module Tools 会自动将 lodash 的代码引用指向子路径。
 
 比如：
 
-``` ts title="input.js"
+```ts title="input.js"
 import _ from 'lodash';
 import { add } from 'lodash/fp';
 
@@ -1211,9 +1212,7 @@ const addOne = _add(1);
 _map([1, 2, 3], addOne);
 ```
 
-### 关闭转换
-
-在个别情况下，lodash 的 import 转换可能会生成不符合预期的代码，此时你可以手动关闭这项优化：
+然而有时候 lodash 的 import 转换可能会生成不符合预期的代码，此时你可以手动关闭这项优化：
 
 ```js title="modern.config.ts"
 export default defineConfig({

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

@@ -9,19 +9,8 @@ sidebar_position: 2
 - 类型：`string | Function`
 - 默认值: `undefined`
 
-## string
 
-字符串的形式可以让你直接使用内置的预设。
-
-```js title="modern.config.ts"
-import { defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  buildPreset: 'npm-library',
-});
-```
-
-### `'npm-library'`
+## `npm-library`
 
 在类 [NPM](https://www.npmjs.com/) 包管理器下使用的 Library 通用模式，包含 `esm` 和 `cjs` 两种 Bundle 产物，并且包含一份类型文件。
 
@@ -68,7 +57,7 @@ export const buildConfig = [
 ];
 ```
 
-### `'npm-library-with-umd'`
+## `npm-library-with-umd`
 
 在类 [NPM](https://www.npmjs.com/) 包管理器下使用，并且 Library 支持类似 [unpkg](https://unpkg.com/) 的模式。在预设 `'npm-library'` 的基础上，额外提供 `umd` 产物。
 
@@ -114,7 +103,7 @@ export const buildConfig = [
 ];
 ```
 
-### `'npm-component'`
+## `npm-component`
 
 在类 [NPM](https://www.npmjs.com/) 包管理器下使用的 组件（库）通用模式。包含 `esm` 和 `cjs` 两种 Bundleless 产物（便于 _[Tree shaking](https://developer.mozilla.org/zh-CN/docs/Glossary/Tree_shaking)_ 优化），以及包含一份类型文件。
 
@@ -154,7 +143,7 @@ export const buildConfig = [
 ];
 ```
 
-### `'npm-component-with-umd'`
+## `npm-component-with-umd`
 
 在类 [NPM](https://www.npmjs.com/) 包管理器下使用的组件（库），同时支持类 [unpkg](https://unpkg.com/) 的模式。 在预设 `'npm-component'` 的基础上，额外提供 `umd` 产物。
 
@@ -198,7 +187,7 @@ export const buildConfig = [
 ];
 ```
 
-### 关于预设值支持的 ECMAScript 版本以及 `{es5...esnext}`
+## `npm-library-{es5...esnext}`
 
 当想要使用支持其他 ECMAScript 版本的 `buildPreset` 预设的时候，可以直接在 `'npm-library'`、`'npm-library-with-umd'`、`'npm-component'`、`'npm-component-with-umd'` 这些预设值后面增加想要支持的版本。
 
@@ -212,10 +201,11 @@ export default defineConfig({
 });
 ```
 
-## Function
+## string / Function
 
-函数的配置方式，可以通过 `preset` 参数获取到预设值，然后对里面的构建配置进行修改来自定义你的构建配置。
-以下是一个函数的配置方式的例子，它配置了压缩构建产物的功能：
+buildPreset 除了支持基本的字符串形式，还支持函数形式，可以通过 `preset` 或者 `extendPreset` 参数获取我们提供的预设值，然后进行修改。
+
+以下是两个分别使用 `preset` 和 `extendPreset` 的例子：
 
 ```js title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
@@ -224,10 +214,8 @@ export default defineConfig({
   buildPreset({ preset }) {
     const { NPM_LIBRARY } = preset;
     return NPM_LIBRARY.map(config => {
-      config.minify = {
-        compress: {
-          drop_console: true,
-        },
+      config.define = {
+        VERSION: '1.0.1',
       };
       return config;
     });
@@ -235,52 +223,7 @@ export default defineConfig({
 });
 ```
 
-### 函数参数
-
-`buildPreset` 的函数形式包含了一个对象形式的函数参数。该对象包含以下字段：
-
-* `preset`
-* `extendPreset`
-
-#### `preset`
-
-类型：**Object**
-
-包含了所有可用的构建预设对应的构建配置。可以通过 `buildPreset` 所支持的字符串来使用构建配置，也可以使用这些字符串的下划线命令的方式。下面是两种方式的使用示例：
-
-- 使用 `buildPreset` 所支持的字符串。
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  buildPreset({ preset }) {
-    return preset['npm-library'];
-  },
-});
-```
-
-- 使用 `buildPreset` 所支持的字符串的下划线命名方式。
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/module-tools';
-
-export default defineConfig({
-  buildPreset({ preset }) {
-    return preset.NPM_LIBRARY;
-  },
-});
-```
-
-#### `extendPreset`
-
-类型：`Function`
-
-用于扩展某个 `buildPreset` 的工具函数，可以修改 `buildPreset` 对应的构建配置。
-
-> 底层使用类似 `{...oldBuildConfig, ...extendBuildConfig}` 方式进行处理。
-
-例如在 `'npm-library'` 构建预设的基础上增加 `define` 配置：
+`extendPreset` 里会使用 lodash.merge 进行配置合并
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';

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

@@ -2,7 +2,7 @@
 sidebar_position: 7
 ---
 
-# 处理静态资源文件
+# 处理静态资源
 
 模块工程会对代码中使用的静态资源进行处理。如果需要配置，则可以使用 [`buildConfig.asset`](/api/config/build-config#asset) API。
 
@@ -16,10 +16,10 @@ sidebar_position: 7
 
 对于静态文件的处理，模块工程目前默认支持的功能有：
 
-- 设置静态资源路径为 `./assets`。
+- 输出静态资源至 `./assets`。
 - 对于不超过 **10kb** 的文件会内联到代码中。
 
-### 示例
+## 示例
 
 让我们看下面的例子：
 
@@ -27,7 +27,6 @@ sidebar_position: 7
 
 ```ts title="./src/asset.ts"
 import img from './bg.png';
-console.log(img);
 ```
 
 - 如果 `bg.png` 的大小小于 10 kb，则此时产物目录结构和产物内容为：
@@ -39,7 +38,6 @@ console.log(img);
 
 ```js title="./dist/asset.js"
 var img_default = 'data:image/png;base64,';
-console.info(img_default);
 ```
 
 - 如果 `bg.png` 的大小大于 10 kb，则此时产物目录结构和产物内容为：
@@ -53,7 +51,6 @@ console.info(img_default);
 
 ```js title="./dist/asset.js"
 import img from './assets/bg.13e2aba2.png';
-console.info(img);
 ```
 
 当你想要修改默认行为的时候，可以使用以下 API：

package/docs/zh/guide/advance/copy.md

@@ -13,8 +13,6 @@ sidebar_position: 3
 - [`patterns`](/api/config/build-config#copypatterns)
 - [`options`](/api/config/build-config#copyoptions)
 
-在开始学习之前可以先花一些时间了解它们。
-
 ## API 详解
 
 `copy.patterns` 用于寻找复制的文件以及配置输出的路径。

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

@@ -2,7 +2,7 @@
 sidebar_position: 4
 ---
 
-# 如何处理第三方依赖
+# 处理三方依赖
 
 一般来说，项目所需要的第三方依赖可以通过包管理器的 `install` 命令安装，在安装第三方依赖成功后，这些第三方依赖一般会出现在项目 `package.json` 的 `dependencies` 和 `devDependencies` 下。