@modern-js/module-tools-docs 2.0.0-beta.4

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

@@ -0,0 +1,501 @@
+# BuildConfig
+This section describes all the configuration of Module tools for building
+## alias
+- type: `Record<string, string | string[]> | Function`
+- default: `{'@': 'src',}`
+
+:::tip
+For TypeScript projects, you only need to configure [compilerOptions.paths](https://www.typescriptlang.org/tsconfig#paths) in `tsconfig.json`, Module tools will automatically recognize the alias in `tsconfig.json`, so there is no need to configure the `alias` field additionally.
+:::
+
+```js
+export default {
+  build: {
+    alias: {
+      '@common': '. /src/common',
+    },
+  },
+};
+```
+
+After the above configuration is done, if `@common/Foo.tsx` is referenced in the code, it will map to the `<root>/src/common/Foo.tsx` path.
+
+When the value of `alias` is defined as a function, you can accept the pre-defined alias object and modify it.
+
+```js
+export default {
+  build: {
+    alias: alias => {
+      alias['@common'] = '. /src/common';
+    },
+  },
+};
+```
+
+It is also possible to return a new object as the final result in the function, which will override the pre-defined alias object.
+
+```js
+export default {
+  build: {
+    alias: alias => {
+      return {
+        '@common': '. /src/common',
+      };
+    },
+  },
+};
+```
+
+## asset
+
+### path
+Static resource output path, will be based on [outdir](/zh/api/build-config/#outdir)
+
+- type: `string`
+- default: `assets`
+
+### limit
+Threshold for automatically inlining static resources when building, resources less than 10240 bytes will be automatically inlined into the bundle product
+
+- type: `number`
+- default: `10 * 1024`
+
+### publicPath
+The CDN prefix given to unlinked resources when packaging
+- type: `string`
+- default: `undefined`
+```js
+export default {
+  build: {
+    asset: {
+      publicPath: 'https://xxx/'
+    }
+  }
+};
+```
+At this point, all static resources will be prefixed with `https://xxx/`
+
+### svgr
+Treat svg as a React component when packaging
+- type: `boolean | Object`
+
+#### include
+Set the matching svg file
+- type: `string | RegExp | (string | RegExp)[]`
+- default: `/\.svg$/`
+
+#### exclude
+Set unmatched svg files
+- type: `string | RegExp | (string | RegExp)[]`
+- default: `undefined`
+
+
+## autoExternal
+Automatically externalize project dependencies and peerDependencies and not package them into the final bundle
+- type: `boolean | Object`
+- default: `true`
+
+### dependencies
+Whether or not the dep dependencies of the external project are needed
+- type: `boolean`
+- default: `true`
+
+### peerDependencies
+Whether to require peerDep dependencies for external projects
+- type: `boolean`
+- default: `true`
+
+## buildType
+The build type, `bundle` will package your code, `bundleless` will only do the code conversion
+- type: `'bundle' | 'bundleless'`
+- default: `bundle`
+
+## copy
+Copies the specified file or directory into the build output directory
+- type: `Array`
+- default: `[]`
+``js
+
+export default {
+  build: {
+    copy: [{ from: '. /src/assets', to: '' }],
+  },
+};
+```
+Reference for array settings: [copy-webpack-plugin patterns](https://github.com/webpack-contrib/copy-webpack-plugin#patterns)
+
+## define
+Define global variables that will be injected into the code
+- type: `Record<string, string>`
+- default: `{}`
+
+Since the `define` function is implemented by global text replacement, you need to ensure that the global variable values are strings. A safer approach is to convert the value of each global variable to a string, using `JSON.stringify`, as follows.
+```js
+export default {
+  build: {
+    define: {
+      'VERSION': JSON.stringify('1.0'),
+
+    },
+  },
+};
+```
+
+:::tip
+To prevent excessive global replacement substitution, it is recommended that the following two principles be followed when using
+- Use upper case for global constants
+- Customize the prefix and suffix of global constants to ensure uniqueness
+:::
+
+## dts
+The dts file generates the relevant configuration, by default it generates
+
+- type: `false | Object`
+- default: `{}`
+
+### tsconfigPath
+Path to the tsconfig file
+- type: `string`
+- default: `. /tsconfig.json`
+
+### distPath
+The output path of the dts file, based on [outdir]('/zh/api/build-config/#outdir')
+- type: `string`
+- default: `. /types`
+
+### only
+Generate only dts files, not js files
+- type: `boolean`
+- default: `false`
+
+## externals
+Configure external dependencies that will not be packaged into the final bundle
+- type: `(string | RegExp)[]`
+- default: `[]`
+## format
+The format of the js product output, where `iife` and `umd` can only take effect when `buildType` is `bundle`
+- type: `'esm' | 'cjs' | 'iife' | 'umd'`
+- default: `cjs`
+
+## input
+Specify the entry file for the build, in the form of an array that can specify the directory
+- type: `string[] | Record<string, string>`
+- default: `['src/index.ts']` in `bundle` mode, `['src']` in `bundleless` mode
+
+```js
+export default {
+  build: {
+    input: ['src/index.ts', 'src/index2.ts'],
+  },
+};
+```
+
+## jsx
+Specify the compilation method of jsx, default support React17, automatically inject jsx runtime code
+- type: `automatic | classic`
+- default: `automatic`
+
+## minify
+Use esbuild or terser to compress code, also pass [terserOptions](https://github.com/terser/terser#minify-options)
+- type: `'terser' | 'esbuild' | false | Object`
+- default: `false`
+
+```js
+export default {
+  build: {
+    minify: {
+      compress: {
+        drop_console: true,
+      },
+    },
+  },
+};
+```
+
+## outdir
+Specifies the output directory of the build
+- type: `string`
+- default: `dist`
+
+## 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`
+
+## sourceDir
+Specify the source directory of the build, default is `src`, which is used to generate the corresponding product directory based on the source directory structure when building `bundleless`.
+- type: `string`
+- default: `src`
+
+## sourceMap
+Whether to generate sourceMap or not
+- type: `boolean | 'inline' | 'external'`
+- default: `false`
+
+## splitting
+Whether to enable code splitting
+- type: `boolean`
+- default: `false`
+
+## style
+Configure style-related configuration
+
+### less
+less-related configuration
+#### lessOptions
+Refer to [less](https://less.bootcss.com/usage/#less-options) for detailed configuration
+- type: `Object`
+- default: `{ javascriptEnabled: true }`
+
+#### additionalData
+Add `Less` code to the beginning of the entry file.
+- type: `string`
+- default: `undefined`
+
+```js
+export default {
+  build: {
+    style: {
+      less: {
+        additionalData: `@base-color: #c6538c;`,
+      },
+    }
+  }
+}
+
+```
+#### implementation
+Configure the implementation library used by `Less`, if not specified, the built-in version used is `4.1.3`
+- type: `string | Object`
+- default: `undefined`
+
+Specify the implementation library for `Less` when the `Object` type is specified
+```js
+export default {
+  build: {
+    style: {
+      less: {
+        implementation: require('less'),
+      },
+    }
+  }
+}
+```
+
+For the `string` type, specify the path to the implementation library for `Less`
+```js
+export default {
+  build: {
+    style: {
+      less: {
+        implementation: require.resolve('less'),
+      },
+    }
+  }
+}
+```
+
+### sass
+sass-related configuration
+#### sassOptions
+Refer to [node-sass](https://github.com/sass/node-sass#options) for detailed configuration
+- type: `Object`
+- default: `{}`
+#### additionalData
+Add `Sass` code to the beginning of the entry file.
+- type: `string | Function`
+- default: `undefined`
+```js
+export default {
+  build: {
+    style: {
+      sass: {
+        additionalData: `$base-color: #c6538c;
+          $border-dark: rgba($base-color, 0.88);`,
+      },
+    }
+  }
+}
+```
+
+#### implementation
+Configure the implementation library used by `Sass`, the built-in version used is `1.5.4` if not specified
+- type: `string | Object`
+- default: `undefined`
+
+Specify the implementation library for `Sass` when the `Object` type is specified
+```js
+export default {
+  build: {
+    style: {
+      sass: {
+        implementation: require('sass'),
+      },
+    }
+  }
+}
+```
+
+For the `string` type, specify the path to the `Sass` implementation library
+```js
+export default {
+  build: {
+    style: {
+      sass: {
+        implementation: require.resolve('sass'),
+      },
+    }
+  }
+}
+```
+
+### postcss
+- plugins
+- processOptions
+
+See [postcss](https://github.com/postcss/postcss#options) for detailed configuration
+### inject
+Configure whether to insert style into js in packaged mode
+
+- type: `boolean`
+- default: `false`
+
+### autoModules
+Enable CSS Modules automatically based on the filename.
+
+- type: `boolean | RegExp`
+- default: `true `
+
+`true` : Enables CSS Modules for style files ending with `.module.css` `.module.less` `.module.scss` `.module.sass` filenames
+
+`false` : Disable CSS Modules.
+
+`RegExp` : Enables CSS Modules for all files that match the regular condition.
+
+### modules
+CSS Modules configuration
+
+- type: `Object`
+- default: `{}`
+
+A common configuration is ``localsConvention``, which changes the class name generation rules for css modules
+```js
+export default {
+  build: {
+    style: {
+      modules: {
+        localsConvention: 'camelCaseOnly',
+      },
+    }
+  }
+}
+```
+For the following styles
+```css
+.box-title {
+  color: red;
+}
+```
+You can use ``styles.boxTitle`` to access
+
+
+For detailed configuration see [postcss-modules](https://github.com/madyankin/postcss-modules#usage)
+
+### tailwind
+tailwindcss related configuration
+
+- type: `Object | Function`
+- default: `see configuration details below`
+
+<details>
+  <summary>TailwindCSS configuration details</summary>
+
+```js
+  const tailwind = {
+    purge: {
+        enabled: options.env === 'production',
+        content: [
+          '. /config/html/**/*.html',
+          '. /config/html/**/*.ejs',
+          '. /config/html/**/*.hbs',
+          '. /src/**/*',
+        ],
+        layers: ['utilities'],
+    },
+    // https://tailwindcss.com/docs/upcoming-changes
+    future: {
+      removeDeprecatedGapUtilities: false,
+      purgeLayersByDefault: true,
+      defaultLineHeights: false,
+      standardFontWeights: false,
+    },
+  }
+```
+
+When the value is of type `Object`, it is merged with the default configuration via `Object.assign`.
+
+When the value is of type `Function`, the object returned by the function is merged with the default configuration via `Object.assign`.
+
+The `theme` property is not allowed, otherwise the build will fail, using [`designSystem`](/zh/api/design-system) as the `Tailwind CSS Theme` configuration.
+
+The rest of the usage is the same as Tailwind CSS: [Quick Portal](https://tailwindcss.com/docs/configuration).
+
+
+## target
+Specify the target environment for the build
+- type: `'es5' | 'es6' | 'es2015' | 'es2016' | 'es2017' | 'es2018' | 'es2019' | 'es2020' | 'es2021' | 'es2022' | 'esnext'`
+- default: `'es2015'`
+
+
+## umdGlobals
+Specify global variables for external import of umd products
+- type: `Record<string, string>`
+- default: `{}`
+
+```js
+export default {
+  build: {
+    umdGlobals: {
+      react: 'React',
+      'react-dom': 'ReactDOM',
+    },
+  }
+}
+```
+At this point, `react` and `react-dom` will be seen as global variables imported externally and will not be packed into the umd product, but will be accessible by way of `global.React` and `global.ReactDOM`
+
+## umdModuleName
+Specifies the module name of the umd product
+
+- type: `string` | `Function`
+- default: `name => name`
+
+``js
+export default {
+  build: {
+    format: 'umd',
+    umdModuleName: 'myLib',
+  }
+}
+```
+At this point the umd product will go to mount on `global.myLib`
+:::tip
+- The module name of the umd product must not conflict with the global variable name.
+- Module names should not contain special characters like `-`, `@`, `/`, etc.
+:::
+
+Also the function form can take one parameter, which is the output path of the current package file
+```js
+export default {
+  build: {
+    format: 'umd',
+    umdModuleName: (path) => {
+      if (path.includes('index')) {
+        return 'myLib';
+      } else {
+        return 'myLib2';
+      }
+    },
+  }
+}
+```

package/docs/en/api/build-preset.md

@@ -0,0 +1,214 @@
+# BuildPreset
+A build preset string or preset function. Provides out-of-the-box build configuration
+
+- type: `string | Function`
+- default: `undefined`
+
+
+## string
+
+The string form allows you to use the built-in presets directly
+
+```js
+export default {
+  buildPreset: 'npm-library',
+};
+```
+
+
+### ``npm-library'`
+Library generic schema used under class [NPM](https://www.npmjs.com/) package manager, contains `esm` and `cjs` Bundle products, and includes a type file.
+
+:::info
+About the class [NPM](https://www.npmjs.com/) Package Manager
+* [npm](https://www.npmjs.com)
+* [yarn](https://yarnpkg.com/)
+* [pnpm](https://pnpm.io/)
+:::
+
+```json title="package.json"
+{
+    "main": ". /dist/lib/index.js",
+    "module": ". /dist/es/index.js",
+    "types": ". /dist/types/index.d.ts",
+}
+```
+The build configuration corresponding to the preset string.
+```js
+export const buildConfig = [
+  {
+    format: 'cjs',
+    target: 'es6',
+    buildType: 'bundle',
+    outdir: '. /lib',
+  },
+  {
+    format: 'esm',
+    target: 'es6',
+    buildType: 'bundle',
+    outdir: '. /es',
+  },
+  {
+    buildType: 'bundle',
+    outdir: '. /types',
+    dts: {
+      only: true,
+    },
+  },
+];
+```
+
+### ``npm-library-with-umd'``
+Used under class [NPM](https://www.npmjs.com/) package manager, and Library supports a similar pattern to [unpkg](https://unpkg.com/). Additional ``umd`` products are provided on top of the pre-defined ``npm-library'`.
+
+```json title="package.json"
+{
+    "main": ". /dist/lib/index.js",
+    "module": ". /dist/es/index.js",
+    "types": ". /dist/types/index.d.ts",
+    "unpkg": ". /dist/umd/index.js",
+};
+```
+The build configuration corresponding to the preset string.
+```js
+export const buildConfig = [
+  {
+    format: 'cjs',
+    target: 'es6',
+    buildType: 'bundle',
+    outdir: '. /lib',
+  },
+  {
+    format: 'esm',
+    target: 'es6',
+    buildType: 'bundle',
+    outdir: '. /es',
+  },
+  {
+    format: 'umd',
+    target: 'es6',
+    buildType: 'bundle',
+    outdir: '. /umd',
+  },
+  {
+    buildType: 'bundle',
+    outdir: '. /types',
+    dts: {
+      only: true,
+    },
+  },
+];
+```
+
+### `'npm-component'`
+A generic pattern for components (libraries) used under the class [NPM](https://www.npmjs.com/) package manager. Contains both `esm` and `cjs` Bundleless products (for easy *[Tree shaking](https://developer.mozilla.org/zh-CN/docs/Glossary/Tree_shaking)* optimization), as well as including a copy of the type file.
+
+For style files included in the source code, the products provide the compiled product of the style and the source file of the style.
+
+```json title="package.json"
+{
+    "main": ". /dist/lib/index.js", // bundleless type
+    "module": ". /dist/es/index.js", // bundleless type
+    "types": ". /dist/types/index.d.ts",
+};
+```
+The pre-defined strings correspond to the build configuration.
+
+``` js
+export const buildConfig = [
+  {
+    format: 'cjs',
+    target: 'es6',
+    buildType: 'bundleless',
+    outdir: '. /lib',
+  },
+  {
+    format: 'esm',
+    target: 'es6',
+    buildType: 'bundleless',
+    outdir: '. /es',
+  },
+  {
+    buildType: 'bundleless',
+    outdir: '. /types',
+    dts: {
+      only: true,
+    },
+  },
+];
+```
+
+### `'npm-component-with-umd'`
+
+Component (library) used under class [NPM](https://www.npmjs.com/) package manager, with support for class [unpkg](https://unpkg.com/) schema. Additional ``umd`` products are provided on top of the pre-defined ``npm-component'`.
+```json title="package.json"
+{
+    "main": ". /dist/lib/index.js", // bundleless type
+    "module": ". /dist/es/index.js", // bundleless type
+    "types": ". /dist/types/index.d.ts",
+    "unpkg": ". /dist/umd/index.js",
+};
+```
+```js
+export const buildConfig = [
+  {
+    format: 'cjs',
+    target: 'es6',
+    buildType: 'bundleless',
+    outdir: '. /lib',
+  },
+  {
+    format: 'esm',
+    target: 'es6',
+    buildType: 'bundleless',
+    outdir: '. /es',
+  },
+   {
+    format: 'umd',
+    target: 'es6',
+    buildType: 'bundle',
+    outdir: '. /umd',
+  },
+  {
+    buildType: 'bundleless',
+    outdir: '. /types',
+    dts: {
+      only: true,
+    },
+  },
+];
+```
+
+### About the ECMAScript versions supported by the preset and `{es5.... .esnext}`
+
+
+When you want to use a `buildPreset` preset that supports other ECMAScript versions, you can directly add the supported versions to the `'npm-library'`, `'npm-library-with-umd'`, `'npm-component'`, `'npm-component-with-umd'` presets.
+
+For example, if you want the ``npm-library'` preset to support ``es2017``, you can configure it as follows.
+
+```js
+export default {
+  buildPreset: 'npm-library-es2017',
+};
+```
+
+## Function
+
+The way the function is configured, you can get the preset value with the `preset` parameter and then modify the build configuration inside to customize your build configuration.
+The following is an example of how a function can be configured to compress a build product.
+
+```js
+export default {
+  buildPreset({ preset }) {
+    const { NPM_LIBRARY } = preset;
+    return NPM_LIBRARY.map(config => {
+      config.minify = {
+        compress: {
+          drop_console: true,
+        },
+      };
+      return config;
+    });
+  },
+}
+```