@modern-js/main-doc 2.42.1 → 2.43.0

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/css.mdx

@@ -22,7 +22,7 @@ Please refer to [Modern.js Builder - Using PostCSS](https://modernjs.dev/builder
 
 ## Using CSS Modules
 
-Please read the [Using CSS Modules](https://modernjs.dev/builder/en/guide/basic/css-modules.html) section to learn about the complete usage of CSS Modules.
+Please read the [Using CSS Modules](/guides/basic-features/css-modules) section to learn about the complete usage of CSS Modules.
 
 ## Using CSS-in-JS
 
@@ -72,18 +72,7 @@ To use [Tailwind CSS](https://tailwindcss.com/) in Modern.js, you can follow the
 ? Please select the feature name: Enable Tailwind CSS
 ```
 
-After successful initialization, you will see the following additions to the `package.json` file:
-
-```json title="./package.json"
-{
-  "dependencies": {
-    "tailwindcss": "^3.0.0"
-  },
-  "devDependencies": {
-    "@modern-js/plugin-tailwindcss": "^2.0.0"
-  }
-}
-```
+After successful initialization, you will see that the `package.json` has added dependencies for `tailwindcss` and `@modern-js/plugin-tailwindcss`.
 
 2. Register the Tailwind plugin in `modern.config.ts`:
 

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;
+}
+```

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

@@ -0,0 +1,173 @@
+---
+sidebar_position: 10
+---
+
+# Output Files
+
+This chapter will introduces the directory structure of output files and how to control the output directory of different types of files.
+
+## Default Directory Structure
+
+The following is a basic directory for output files. By default, the compiled files will be output in the `dist` directory of current project.
+
+```bash
+dist
+├── static
+│   ├── css
+│   │   ├── [name].[hash].css
+│   │   └── [name].[hash].css.map
+│   │
+│   └── js
+│       ├── [name].[hash].js
+│       ├── [name].[hash].js.LICENSE.txt
+│       └── [name].[hash].js.map
+│
+└── html
+    └── [name]
+        └── index.html
+```
+
+The most common output files are HTML files, JS files, and CSS files:
+
+- HTML files: default output to the `html` directory.
+- JS files: default output to `static/js` directory,
+- CSS files: default output to the `static/css` directory.
+
+In addition, JS files and CSS files sometimes generate some related files:
+
+- License files: contains open source license, which is output to the same level directory of the JS file, and adds `.LICENSE.txt` suffix.
+- Source Map files: contains the source code mappings, which is output to the same level directory of JS files and CSS files, and adds a `.map` suffix.
+
+In the filename, `[name]` represents the entry name corresponding to this file, such as `index`, `main`. `[hash]` is the hash value generated based on the content of the file.
+
+## Modify the Directory
+
+Builder provides some configs to modify the directory or filename, you can:
+
+- Modify the filename through [output.filename](/configure/app/output/filename).
+- Modify the output path of through [output.distPath](/configure/app/output/dist-path).
+- Modify the license file through [output.legalComments](/configure/app/output/legal-comments).
+- Remove Source Map file through [output.disableSourceMap](/configure/app/output/disable-source-map).
+- Remove the folder corresponding to the HTML files through [html.disableHtmlFolder](/configure/app/html/disable-html-folder).
+
+## Static Assets
+
+When you import static assets such as images, SVG, fonts, media, etc. in the code, they will also be output to the `dist/static` directory, and automatically assigned to the corresponding subdirectories according to the file type:
+
+```bash
+dist
+└── static
+    ├── image
+    │   └── foo.[hash].png
+    │
+    ├── svg
+    │   └── bar.[hash].svg
+    │
+    ├── font
+    │   └── baz.[hash].woff2
+    │
+    └── media
+        └── qux.[hash].mp4
+```
+
+You can use the [output.distPath](/configure/app/output/dist-path) config to uniformly input these static assets into a directory, for example, output to the `assets` directory:
+
+```ts
+export default {
+  output: {
+    distPath: {
+      image: 'assets',
+      svg: 'assets',
+      font: 'assets',
+      media: 'assets',
+    },
+  },
+};
+```
+
+The above config produces the following directory structure:
+
+```bash
+dist
+└── assets
+    ├── foo.[hash].png
+    ├── bar.[hash].svg
+    ├── baz.[hash].woff2
+    └── qux.[hash].mp4
+```
+
+## Node.js Output Directory
+
+When you enable SSR or SSG features in Modern.js, Modern.js will generate a Node.js bundle after the build and output it to the `bundles` directory.
+
+```bash
+dist
+├── bundles
+│   └── [name].js
+├── static
+└── html
+```
+
+Node.js files usually only contain JS files, no HTML or CSS. Also, JS file names will not contain hash.
+
+You can modify the output path of Node.js files through the [output.distPath.server](/configure/app/output/dist-path) config.
+
+For example, output Node.js files to the `server` directory:
+
+```ts
+export default {
+  output: {
+    distPath: {
+      server: 'server',
+    },
+  },
+};
+```
+
+## Flatten the Directory
+
+Sometimes you don't want the dist directory to have too many levels, you can set the directory to an empty string to flatten the generated directory.
+
+See the example below:
+
+```ts
+export default {
+  output: {
+    distPath: {
+      js: '',
+      css: '',
+      html: '',
+    },
+  },
+  html: {
+    disableHtmlFolder: true,
+  }
+};
+```
+
+The above config produces the following directory structure:
+
+```bash
+dist
+├── [name].[hash].css
+├── [name].[hash].css.map
+├── [name].[hash].js
+├── [name].[hash].js.map
+└── [name].html
+```
+
+## Not Written to Disk
+
+By default, Modern.js will write the generated files to disk, so developers can view the file content or configure proxy rules for static assets.
+
+In development, you can choose to keep the generated files in the Dev Server's memory to reduce the overhead of file operations.
+
+Just set the `dev.writeToDisk` config to `false`:
+
+```ts
+export default {
+  dev: {
+    writeToDisk: false,
+  },
+};
+```

package/docs/en/guides/basic-features/static-assets.mdx

@@ -0,0 +1,165 @@
+---
+sidebar_position: 10
+---
+
+# Import Static Assets
+
+Modern.js supports import static assets, including images, fonts, and medias.
+
+:::tip What is Static Assets
+Static assets are files that are part of a web application and do not change, even when the application is being used. Examples of static assets include images, fonts, medias, stylesheets, and JavaScript files. These assets are typically stored on a web server or CDN, and delivered to the user's web browser when the Web application is accessed. Because they do not change, static assets can be cached by the browser, which helps to improve the performance of the Web application.
+:::
+
+## Assets Format
+
+The following are the formats supported by Modern.js by default:
+
+- **Image**: png, jpg, jpeg, gif, svg, bmp, webp, ico, apng, avif, tiff.
+- **Fonts**: woff, woff2, eot, ttf, otf, ttc.
+- **Media**: mp4, webm, ogg, mp3, wav, flac, aac, mov.
+
+If you need to import assets in other formats, please refer to [Extend Asset Types](#extend-asset-types).
+
+:::tip SVG images
+SVG image is a special case. Modern.js support convert SVG to React components, so SVG is processed separately. For details, see [Import SVG Assets](/guides/basic-features/svg-assets.html).
+:::
+
+## Import Assets in JS file
+
+In JS files, you can directly import static assets in relative paths:
+
+```tsx
+// Import the logo.png image in the static directory
+import logo from './static/logo.png';
+
+export default = () => <img src={logo} />;
+```
+
+Import with [alias](/guides/basic-features/alias.html) are also supported:
+
+```tsx
+import logo from '@/static/logo.png';
+
+export default = () => <img src={logo} />;
+```
+
+## Import Assets in CSS file
+
+In CSS files, you can reference static assets in relative paths:
+
+```css
+.logo {
+  background-image: url('../static/logo.png');
+}
+```
+
+Import with [alias](/guides/basic-features/alias.html) are also supported:
+
+```css
+.logo {
+  background-image: url('@/static/logo.png');
+}
+```
+
+## Import Results
+
+The result of importing static assets depends on the file size:
+
+- When the file size is greater than 10KB, a URL will be returned, and the file will be output to the dist directory.
+- When the file size is less than 10KB, it will be automatically inlined to Base64 format.
+
+```js
+import largeImage from './static/largeImage.png';
+import smallImage from './static/smallImage.png';
+
+console.log(largeImage); // "/static/largeImage.6c12aba3.png"
+console.log(smallImage); // "data:image/png;base64,iVBORw0KGgo..."
+```
+
+For a more detailed introduction to asset inlining, please refer to the [Static Asset Inlining](/guides/advanced-features/inline-assets) chapter.
+
+## Output Files
+
+When static assets are imported, they will be output to the dist directory. You can:
+
+- Modify the output filename through [output.filename](/configure/app/output/filename).
+- Modify the output path through [output.distPath](/configure/app/output/dist-path).
+
+Please read [Output Files](/guides/basic-features/output-files) for details.
+
+## URL Prefix
+
+The URL returned after importing a asset will automatically include the path prefix:
+
+- In development, using [dev.assetPrefix](/configure/app/dev/asset-prefix) to set the path prefix.
+- In production, using [output.assetPrefix](/configure/app/output/asset-prefix) to set the path prefix.
+
+For example, you can set `output.assetPrefix` to `https://modern.com`:
+
+```js
+import logo from './static/logo.png';
+
+console.log(logo); // "https://modern.com/static/logo.6c12aba3.png"
+```
+
+## Add Type Declaration
+
+When you import static assets in TypeScript code, TypeScript may prompt that the module is missing a type definition:
+
+```
+TS2307: Cannot find module './logo.png' or its corresponding type declarations.
+```
+
+To fix this, you need to add a type declaration file for the static assets, please create a `src/global.d.ts` file, and add the corresponding type declaration. Taking png images as an example, you need to add the following declarations:
+
+```ts title="src/global.d.ts"
+declare module '*.png' {
+  const content: string;
+  export default content;
+}
+```
+
+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.
+
+## Extend Asset Types
+
+If the built-in asset types in Modern.js cannot meet your requirements, you can modify the built-in webpack/Rspack configuration and extend the asset types you need using [tools.bundlerChain](/configure/app/tools/bundler-chain).
+
+For example, if you want to treat `*.pdf` files as assets and directly output them to the dist directory, you can add the following configuration:
+
+```ts
+export default {
+  tools: {
+    bundlerChain(chain) {
+      chain.module
+        .rule('pdf')
+        .test(/\.pdf$/)
+        .type('asset/resource');
+    },
+  },
+};
+```
+
+After adding the above configuration, you can import `*.pdf` files in your code, for example:
+
+```js
+import myFile from './static/myFile.pdf';
+
+console.log(myFile); // "/static/myFile.6c12aba3.pdf"
+```
+
+For more information about asset modules, please refer to:
+
+- [Rspack Documentation - Asset modules](https://www.rspack.dev/guide/asset-module.html#asset-modules)
+- [webpack Documentation - Asset modules](https://webpack.js.org/guides/asset-modules/)
+
+## Image Format
+
+When using image assets, you can choose a appropriate image format according to the pros and cons in the table below.
+
+| Format | Pros                                                                                                      | Cons                                                                                | Scenarios                                                                                                                                              |
+| ------ | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| PNG    | Lossless compression, no loss of picture details, no distortion, support for translucency                 | Not suitable for pictures with complex color tables                                 | Suitable for pictures with few colors and well-defined borders, suitable for logos, icons, transparent images and other scenes                         |
+| JPG    | Rich colors                                                                                               | Lossy compression, which will cause image distortion, does not support transparency | Suitable for pictures with a large number of colors, gradients, and overly complex pictures, suitable for portrait photos, landscapes and other scenes |
+| WebP   | Supports both lossy and lossless compression, supports transparency, and is much smaller than PNG and JPG | iOS compatibility is not good                                                       | Pixel images of almost any scene, and the hosting environment that supports WebP, should prefer WebP image format                                      |
+| SVG    | Lossless format, no distortion, supports transparency                                                     | Not suitable for complex graphics                                                   | Suitable for vector graphics, suitable for icons                                                                                                       |