@modern-js/main-doc 2.42.0 → 2.42.2

package/docs/en/guides/advanced-features/inline-assets.mdx

@@ -0,0 +1,161 @@
+---
+sidebar_position: 13
+---
+
+# Inline Static Assets
+
+Inline static assets refer to the practice of including the content of a static asset directly in a HTML or JS file, instead of linking to an external file. This can improve the performance of a website by reducing the number of HTTP requests that the browser has to make to load the page.
+
+However, static assets inlining also has some disadvantages, such as increasing the size of a single file, which may lead to slower loading. Therefore, in the actual scenario, it is necessary to decide whether to use static assets inlining according to the specific situation.
+
+Modern.js will automatically inline static assets that are less than 10KB, but sometimes you may need to manually control assets to force them to be inlined or not, and this document explains how to precisely control the inlining behavior of static assets.
+
+## Automatic Inlining
+
+By default, Modern.js will inline assets when the file size of is less than a threshold (the default is 10KB). When inlined, the asset will be converted to a Base64 encoded string and will no longer send a separate HTTP request. When the file size is greater than this threshold, it is loaded as a separate file with a separate HTTP request.
+
+The threshold can be modified with the [output.dataUriLimit](/configure/app/output/data-uri-limit) config. For example, set the threshold of images to 5000 Bytes, and set media assets not to be inlined:
+
+```ts
+export default {
+  output: {
+    dataUriLimit: {
+      image: 5000,
+      media: 0,
+    },
+  },
+};
+```
+
+## Force Inlining
+
+You can force an asset to be inlined by adding the `inline` query when importing the asset, regardless of whether the asset's size is smaller than the size threshold.
+
+```tsx
+import React from 'react';
+import img from '. /foo.png?inline';
+
+export default function Foo() {
+  return <img src={img} />;
+}
+```
+
+In the above example, the `foo.png` image will always be inlined, regardless of whether the size of the image is larger than the threshold.
+
+In addition to the `inline` query, you can also use the `__inline` query to force inlining of the asset:
+
+```tsx
+import img from '. /foo.png?__inline';
+```
+
+### Referenced from CSS file
+
+When you reference a static asset in your CSS file, you can also force inline the asset with the `inline` or `__inline` queries.
+
+```css
+.foo {
+  background-image: url('. /icon.png?inline');
+}
+```
+
+:::tip Do you really need to force inlining?
+Inline large assets will significantly increase the first paint time or first contentful paint time of a page, which will hurt user experience. And when you inline a static asset multiple times into a CSS file, the base64 content will be repeatedly injected, causing the bundle size to grow . Please use forced inlining with caution.
+:::
+
+## Force no inlining
+
+When you want to always treat some assets as separate files, no matter how small the asset is, you can add the `url` query to force the asset not to be inlined.
+
+```tsx
+import React from 'react';
+import img from '. /foo.png?url';
+
+export default function Foo() {
+  return <img src={img} />;
+}
+```
+
+In the above example, the `foo.png` image will always be loaded as a separate file, even if the size of the image is smaller than the threshold.
+
+In addition to the `url` query, you can also use the `__inline=false` query to force the asset not to be inlined:
+
+```tsx
+import img from '. /foo.png?__inline=false';
+```
+
+### Referenced from CSS file
+
+When you reference a static asset in your CSS file, you can also force the asset not to be inlined with `url` or `__inline=false` queries.
+
+```css
+.foo {
+  background-image: url('. /icon.png?url');
+}
+```
+
+:::tip Do you really need to exclude assets from inlining?
+Excluding assets from inlining will increase the number of assets that the Web App needs to load. This will reduce the efficiency of loading assets in a weak network environment or in scenarios where HTTP2 is not enabled. Please use force no Inline with caution.
+
+## Inline JS files
+
+In addition to inlining static assets into JS files, Modern.js also supports inlining JS files into HTML files.
+
+Just enable the [output.enableInlineScripts](/configure/app/output/enable-inline-scripts) config, and the generated JS files will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
+
+```ts
+export default {
+  output: {
+    enableInlineScripts: true,
+  },
+};
+```
+
+:::tip
+Inline JS files may cause the single HTML file to be too large, and it will break the HTTP caching. Please use it with caution.
+:::
+
+## Inline CSS files
+
+You can also inline CSS files into HTML files.
+
+Just enable the [output.enableInlineStyles](/configure/app/output/enable-inline-styles) config, the generated CSS file will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.
+
+```ts
+export default {
+  output: {
+    enableInlineStyles: true,
+  },
+};
+```
+
+## Add Type Declaration
+
+When you use URL queries such as `?inline` and `?url` in TypeScript code, TypeScript may prompt that the module is missing a type definition:
+
+```
+TS2307: Cannot find module './logo.png?inline' or its corresponding type declarations.
+```
+
+To fix this, you can add type declarations for these URL queries, please create `src/global.d.ts` file and add the following type declarations:
+
+```ts
+declare module '*?inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?__inline' {
+  const content: string;
+  export default content;
+}
+
+declare module '*?inline=false' {
+  const content: string;
+  export default content;
+}
+```

package/docs/en/guides/advanced-features/optimize-bundle.mdx

@@ -44,9 +44,9 @@ See the [performance.bundleAnalyze](/configure/app/performance/bundle-analyze.ht
 
 ## Adjust Browserslist
 
-The Builder will compile the code according to the project's Browserslist config, and inject some Polyfills. If the project does not need to be compatible with legacy browsers, you can adjust the Browserslist and drop some legacy browsers, thereby reducing the compilation overhead on syntax and polyfill.
+Modern.js will compile the code according to the project's Browserslist config, and inject some Polyfills. If the project does not need to be compatible with legacy browsers, you can adjust the Browserslist and drop some legacy browsers, thereby reducing the compilation overhead on syntax and polyfill.
 
-Builder's default Browserslist config is:
+Modern.js's default Browserslist config is:
 
 ```js
 ['> 0.01%', 'not dead', 'not op_mini all'];
@@ -66,7 +66,7 @@ Please read the [Browserslist](https://modernjs.dev/builder/en/guide/advanced/br
 
 When it is clear that third-party dependencies do not require additional polyfill, you can set [output.polyfill](/configure/app/output/polyfill.html) to `usage`.
 
-In `usage` mode, Builder analyzes the syntax used in the source code and injects the required polyfill code on demand to reduce the size of polyfill.
+In `usage` mode, Modern.js analyzes the syntax used in the source code and injects the required polyfill code on demand to reduce the size of polyfill.
 
 ```js
 export default {
@@ -84,11 +84,12 @@ Please read the [Browser Compatibility](https://modernjs.dev/builder/en/guide/ad
 
 In general front-end projects, the size of image often accounts for a large proportion of the total bundle size of the project.So if the image size can be reduced as much as possible, it will have a significant optimization effect on the project bundle size. You can enable image compression by registering a plugin in the Builder:
 
-```js
+```ts title="modern.config.ts"
 import { builderPluginImageCompress } from '@modern-js/builder-plugin-image-compress';
 
-// Add the plugin to the Builder
-builder.addPlugins([builderPluginImageCompress()]);
+export default {
+  builderPlugins: [builderPluginImageCompress()],
+};
 ```
 
 See details in [plugin-image-compress](https://modernjs.dev/builder/en/plugins/plugin-image-compress.html).

package/docs/en/guides/basic-features/alias.mdx

@@ -4,9 +4,87 @@ sidebar_position: 4
 
 # Path Alias
 
-import Alias from '@modern-js/builder-doc/docs/en/shared/alias';
+Path aliases allow developers to define aliases for modules, making it easier to reference them in code. This can be useful when you want to use a short, easy-to-remember name for a module instead of a long, complex path.
 
-<Alias />
+For example, if you frequently reference the `src/common/request.ts` module in your project, you can define an alias for it as `@request` and then use `import request from '@request'` in your code instead of writing the full relative path every time. This also allows you to move the module to a different location without needing to update all the import statements in your code.
+
+In Modern.js, there are two ways to set up path aliases:
+
+- Through the `paths` configuration in `tsconfig.json`.
+- Through the [source.alias](/configure/app/source/alias) configuration.
+
+## Using `tsconfig.json`'s `paths` Configuration
+
+You can configure aliases through the `paths` configuration in `tsconfig.json`, which is the recommended approach in TypeScript projects as it also resolves the TS type issues related to path aliases.
+
+For example:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      "@common/*": ["./src/common/*"]
+    }
+  }
+}
+```
+
+After configuring, if you reference `@common/Foo.tsx` in your code, it will be mapped to the `<project>/src/common/Foo.tsx` path.
+
+:::tip
+You can refer to the [TypeScript - paths](https://www.typescriptlang.org/tsconfig#paths) documentation for more details.
+:::
+
+## Use `source.alias` Configuration
+
+Modern.js provides the [source.alias](/configure/app/source/alias) configuration option, which corresponds to the webpack/Rspack native [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealias) configuration. You can configure this option using an object or a function.
+
+### Use Cases
+
+Since the `paths` configuration in `tsconfig.json` is written in a static JSON file, it lacks dynamism.
+
+The `source.alias` configuration can address this limitation by allowing you to dynamically set the `source.alias` using JavaScript code, such as based on environment variables.
+
+### Object Usage
+
+You can configure `source.alias` using an object, where the relative paths will be automatically resolved to absolute paths.
+
+For example:
+
+```js
+export default {
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+};
+```
+
+After configuring, if you reference `@common/Foo.tsx` in your code, it will be mapped to the `<project>/src/common/Foo.tsx` path.
+
+### Function Usage
+
+You can also configure `source.alias` as a function, which receives the built-in `alias` object and allows you to modify it.
+
+For example:
+
+```js
+export default {
+  source: {
+    alias: alias => {
+      alias['@common'] = './src/common';
+      return alias;
+    },
+  },
+};
+```
+
+### Priority
+
+The `paths` configuration in `tsconfig.json` takes precedence over the `source.alias` configuration. When a path matches the rules defined in both `paths` and `source.alias`, the value defined in `paths` will be used.
+
+You can adjust the priority of these two options using [source.aliasStrategy](/configure/app/source/alias-strategy).
 
 ## Default Aliases
 

package/docs/en/guides/basic-features/css-modules.mdx

@@ -0,0 +1,228 @@
+---
+sidebar_position: 14
+---
+
+# Use CSS Modules
+
+[CSS Modules](https://github.com/css-modules/css-modules) allows us to write CSS code in a modular way, and these styles can be imported and used in JavaScript files. Using CSS Modules can automatically generate unique class names, isolate styles between different modules, and avoid class name conflicts.
+
+Builder supports CSS Modules by default, you don't need to add additional configuration. Our convention is to use the `[name].module.css` filename to enable CSS Modules.
+
+The following style files are considered CSS Modules:
+
+- `*.module.scss`
+- `*.module.less`
+- `*.module.css`
+
+## Example
+
+- Write style:
+
+```css
+/* button.module.css */
+.error {
+  background: red;
+}
+```
+
+- Using styles:
+
+```tsx
+// Button.tsx
+import React, { Component } from 'react';
+// import style file
+import styles from './button.module.css';
+
+export default () => {
+  return <button className={styles.error}>Error Button</button>;
+};
+```
+
+## Enable CSS Modules for all CSS files
+
+By default, only files ending in `*.module.css` are treated CSS Modules.
+
+If you want to treat all CSS files in the source directory as CSS Modules, you can enable the [output.disableCssModuleExtension](/configure/app/output/disable-css-module-extension) config, for example:
+
+```ts
+export default {
+  output: {
+    disableCssModuleExtension: true,
+  },
+};
+```
+
+When set, the following two files are treated as CSS Modules:
+
+```ts
+import styles1 from './foo.module.css';
+import styles2 from './bar.css';
+```
+
+:::tip
+We do not recommend enabling this config, because after enabling disableCssModuleExtension, CSS Modules files and ordinary CSS files cannot be clearly distinguished, which is not conducive to long-term maintenance.
+:::
+
+## Enable CSS Modules for the specified style file
+
+By default, only files ending in `*.module.css` are treated CSS Modules.
+
+If you want to enable CSS Modules only for specified style files, you can configure [output.cssModules](/configure/app/output/css-modules), for example:
+
+```ts
+export default {
+  output: {
+    cssModules: {
+      auto: resource => {
+        return resource.includes('.module.') || resource.includes('shared/');
+      },
+    },
+  },
+};
+```
+
+## Custom Class Names
+
+Customizing the class names generated by CSS Modules is also a commonly used function, you can use [output.cssModuleLocalIdentName](/configure/app/output/css-modules.html#cssmodulesexportlocalsconvention) to configure it.
+
+```ts
+export default {
+  output: {
+    cssModuleLocalIdentName: '[hash:base64:4]',
+  },
+};
+```
+
+If you need to customize other configs of CSS Modules, you can set them via [tools.cssLoader](/configure/app/tools/css-loader).
+
+## Add Type Declaration
+
+When you import CSS Modules in TypeScript code, TypeScript may prompt that the module is missing a type definition:
+
+```
+TS2307: Cannot find module './index.module.css' or its corresponding type declarations.
+```
+
+To fix this, you need to add a type declaration file for the CSS Modules, please create a `src/global.d.ts` file, and add the corresponding type declaration:
+
+```ts title="src/global.d.ts"
+declare module '*.module.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.module.styl' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+```
+
+If you enabled the `disableCssModuleExtension` config, you also need to add the following types:
+
+```ts title="src/global.d.ts"
+declare module '*.css' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.scss' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.sass' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.less' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+declare module '*.styl' {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+```
+
+After adding the type declaration, if the type error still exists, you can try to restart the current IDE, or adjust the directory where `global.d.ts` is located, making sure the TypeScript can correctly identify the type definition.
+
+## Generate exact type definitions
+
+Although the above method can provide the type of CSS Modules, it cannot accurately prompt which classNames are exported by a certain CSS file.
+
+Builder supports generating accurate type declarations for CSS Modules, you only need to enable the [output.enableCssModuleTSDeclaration](/configure/app/output/enable-css-module-tsdeclaration) config, and then execute the build, Modern.js will generate type declaration files for all CSS Modules.
+
+```ts
+export default {
+  output: {
+    enableCssModuleTSDeclaration: true,
+  },
+};
+```
+
+### Example
+
+For example, there are two files `src/index.ts` and `src/index.module.scss` under a certain folder:
+
+```tsx title="src/index.ts"
+import styles from './index.module.scss';
+
+export default () => {
+  <div>
+    <div className={styles.pageHeader}>Page Header</div>
+  </div>;
+};
+```
+
+```scss title="src/index.module.scss"
+.page-header {
+  color: black;
+}
+```
+
+After executing the build, the `src/index.module.scss.d.ts` type declaration file will be automatically generated:
+
+```ts title="src/index.module.scss.d.ts"
+// This file is automatically generated.
+// Please do not change this file!
+interface CssExports {
+  'page-header': string;
+  pageHeader: string;
+}
+export const cssExports: CssExports;
+export default cssExports;
+```
+
+Then open the `src/index.ts` file again, you will see that the `styles` object already has a exact type.
+
+### Related configuration
+
+In the above example, `src/index.module.scss.d.ts` is generated by compilation, you can choose to commit them to the Git repository, or you can choose to ignore them in the `.gitignore` file:
+
+```bash
+# Ignore auto generated CSS declarations
+*.module.css.d.ts
+*.module.sass.d.ts
+*.module.scss.d.ts
+*.module.less.d.ts
+*.module.styl.d.ts
+```
+
+In addition, if the generated code causes ESLint to report errors, you can also add the above configuration to the `.eslintignore` file.

package/docs/en/guides/basic-features/json-files.mdx

@@ -0,0 +1,106 @@
+---
+sidebar_position: 12
+---
+
+# Import JSON Files
+
+Modern.js supports import JSON files in code, and also supports import [YAML](https://yaml.org/) and [Toml](https://toml.io/en/) files and converting them to JSON format.
+
+## JSON file
+
+You can import JSON files directly in JavaScript files.
+
+### Example
+
+```json title="example.json"
+{
+  "name": "foo",
+  "items": [1, 2]
+}
+```
+
+```js title="index.js"
+import example from './example.json';
+
+console.log(example.name); // 'foo';
+console.log(example.items); // [1, 2];
+```
+
+### Named Import
+
+Modern.js does not support importing JSON files via named import yet:
+
+```js
+import { name } from './example.json';
+```
+
+## YAML file
+
+YAML is a data serialization language commonly used for writing configuration files.
+
+You can directly import `.yaml` or `.yml` files in JavaScript and they will be automatically converted to JSON format.
+
+### Example
+
+```yaml title="example.yaml"
+---
+hello: world
+foo:
+  bar: baz
+```
+
+```js
+import example from './example.yaml';
+
+console.log(example.hello); // 'world';
+console.log(example.foo); // { bar: 'baz' };
+```
+
+### Add type declaration
+
+When you import a YAML file in your TypeScript code, please create a `src/global.d.ts` file in your project and add the corresponding type declaration:
+
+```ts title="src/global.d.ts"
+declare module '*.yaml' {
+  const content: Record<string, any>;
+  export default content;
+}
+
+declare module '*.yml' {
+  const content: Record<string, any>;
+  export default content;
+}
+```
+
+## Toml file
+
+Toml is a semantically explicit, easy-to-read configuration file format.
+
+You can directly import `.toml` files in JavaScript and it will be automatically converted to JSON format.
+
+### Example
+
+```toml title="example.toml"
+hello = "world"
+
+[foo]
+bar = "baz"
+```
+
+```js
+import example from './example.toml';
+
+console.log(example.hello); // 'world';
+console.log(example.foo); // { bar: 'baz' };
+```
+
+### Add type declaration
+
+When you import Toml files in TypeScript code, please create a `src/global.d.ts` file in your project and add the corresponding type declarations:
+
+```ts title="src/global.d.ts"
+declare module '*.toml' {
+  const content: Record<string, any>;
+  export default content;
+}
+```