@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,172 @@
+---
+sidebar_position: 11
+---
+
+# Import SVG Assets
+
+Modern.js supports import SVG assets and transform SVG into React components or URLs.
+
+:::tip What is SVG
+SVG stands for Scalable Vector Graphics. It is a type of image format that uses vector graphics to represent images. Vector graphics are different from raster graphics, which are made up of pixels. Instead, vector graphics use geometric shapes, lines, and curves to represent images. Because vector graphics are not made up of pixels, they can be scaled to any size without losing resolution or quality.
+:::
+
+## Import SVG in JS file
+
+### Default Import
+
+If you use the default import to reference SVG, it will be treated as a static asset and you will get a URL string:
+
+```tsx title="src/component/Logo.tsx"
+import logoURL from './static/logo.svg';
+
+console.log(logoURL); // => "/static/logo.6c12aba3.png"
+```
+
+### Transform to React Component
+
+When referencing SVG assets in JS files, if the import path includes the `?react` suffix, Modern.js will call SVGR to transform the SVG image into a React component:
+
+```tsx title="src/component/Logo.tsx"
+import Logo from './logo.svg?react';
+
+export default () => <Logo />;
+```
+
+Modern.js also supports the following usage, transforming SVG into a React component by named import `ReactComponent`:
+
+```tsx title="src/component/Logo.tsx"
+import { ReactComponent as Logo } from './static/logo.svg';
+
+export default () => <Logo />;
+```
+
+## Modify the Default Export
+
+You can modify the default export of SVG files through the [output.svgDefaultExport](/configure/app/output/svg-default-export) config. For example, set the default export as a React component:
+
+```ts
+export default {
+  output: {
+    svgDefaultExport: 'component',
+  },
+};
+```
+
+Then import the SVG, you'll get a React component instead of a URL:
+
+```tsx title="src/component/Logo.tsx"
+import Logo from './static/logo.svg';
+
+export default () => <Logo />;
+```
+
+## Import SVG in CSS file
+
+When import an SVG in a CSS file, the SVG is treated as a normal static asset and you will get a URL:
+
+```css
+.logo {
+  background-image: url('../static/logo.svg');
+}
+```
+
+## Assets Processing
+
+When SVG is imported not as a React component but as a normal static asset, it is processed exactly the same as other static assets, and it is also affected by rules such as assets inlining and URL prefixing.
+
+Please read the [Import Static Assets](/guides/basic-features/static-assets) section to understand the processing rules for static assets.
+
+## Disable SVGR Processing
+
+By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting [disableSvgr](/configure/app/output/disable-svgr) to true to improve build performance.
+
+```js
+export default {
+  output: {
+    disableSvgr: true,
+  },
+};
+```
+
+## Add type declaration
+
+When you reference an SVG asset in TypeScript code, TypeScript may prompt that the module is missing a type definition:
+
+```
+TS2307: Cannot find module './logo.svg' or its corresponding type declarations.
+```
+
+To fix this, you need to add a type declaration file for the SVG asset, please create a `src/global.d.ts` file, and add the following type declaration:
+
+```ts
+declare module '*.svg' {
+  export const ReactComponent: React.FunctionComponent<
+    React.SVGProps<SVGSVGElement>
+  >;
+
+  const content: string;
+  export default content;
+}
+
+declare module '*.svg?react' {
+  const ReactComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>;
+  export default ReactComponent;
+}
+```
+
+If you set `svgDefaultExport` to `'component'`, then change the type declaration to:
+
+```ts
+declare module '*.svg' {
+  export const ReactComponent: React.FunctionComponent<
+    React.SVGProps<SVGSVGElement>
+  >;
+
+  export default ReactComponent;
+}
+```
+
+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.
+
+## Modify the SVGR configuration
+
+When SVGR is enabled, its default configuration is as follows:
+
+```js
+{
+  svgo: true,
+  svgoConfig: {
+    plugins: [
+      {
+        name: 'preset-default',
+        params: {
+          overrides: {
+            removeViewBox: false,
+          },
+        },
+      },
+      'prefixIds',
+    ],
+  },
+}
+```
+
+If you need to modify the SVGR configuration, you can do the following:
+
+```js
+export default {
+  tools: {
+    bundlerChain: (chain, { CHAIN_ID }) => {
+      chain.module
+        .rule(CHAIN_ID.RULE.SVG)
+        .oneOf(CHAIN_ID.ONE_OF.SVG)
+        .use(CHAIN_ID.USE.SVGR)
+        .tap(options => {
+          // modify svgoConfig
+          options.svgoConfig.plugins[0].params.overrides.removeUselessDefs = false;
+          return options;
+        });
+    },
+  },
+};
+```

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

@@ -0,0 +1,66 @@
+---
+sidebar_position: 13
+---
+
+# Import Wasm Assets
+
+Modern.js supports import WebAssembly assets in code.
+
+:::tip What is WebAssembly
+WebAssembly (Wasm) is a portable, high-performance binary format designed to execute CPU-intensive computing tasks in modern web browsers, bringing performance and reliability similar to native compiled code to the web platform.
+:::
+
+## Import
+
+You can import a WebAssembly module via named import in a JavaScript file:
+
+```js title="index.js"
+import { add } from './add.wasm';
+
+console.log(add); // [native code]
+console.log(add(1, 2)); // 3
+```
+
+WebAssembly modules can also be imported via dynamic import:
+
+```js title="index.js"
+import('./add.wasm').then(({ add }) => {
+  console.log('---- Async Wasm Module');
+  console.log(add); // [native code]
+  console.log(add(1, 2)); // 3
+});
+```
+
+You can also get the path of a WebAssembly module using the `new URL` syntax:
+
+```js title="index.js"
+const wasmURL = new URL('./add.wasm', import.meta.url);
+
+console.log(wasmURL).pathname; // "/static/wasm/[hash].module.wasm"
+```
+
+## Output Directory
+
+When a `.wasm` asset is imported, it will be output by Modern.js to the `dist/static/wasm` directory by default.
+
+You can change the output directory of `.wasm` files via [output.distPath](/configure/app/output/dist-path) config.
+
+```ts
+export default {
+  output: {
+    distPath: {
+      wasm: 'resource/wasm',
+    },
+  },
+};
+```
+
+## Add Type Declaration
+
+When you import a Wasm file in TypeScript code, you usually need to add the corresponding type declaration.
+
+For example, the `add.wasm` file exports an `add()` method, then you can create an `add.wasm.d.ts` file in the same directory and add the corresponding type declaration:
+
+```ts title="add.wasm.d.ts"
+export const add = (num1: number, num2: number) => number;
+```

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

@@ -0,0 +1,164 @@
+---
+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/static-assets/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/page-performance/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 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://rspack.rs/guide/asset-module.html#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                                                                                                       |

package/docs/en/guides/basic-features/testing/_meta.json

@@ -0,0 +1 @@
+["playwright", "rstest", "vitest", "jest", "cypress"]

package/docs/en/guides/basic-features/testing/cypress.mdx

@@ -0,0 +1,95 @@
+# Cypress
+
+Cypress is a framework for E2E testing and component testing.
+
+To use Cypress in Modern.js, you need to install the dependencies first. You can run the following commands:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{ npm: "npm install -D cypress", yarn: "yarn add -D cypress", pnpm: "pnpm install -D cypress" }} />
+
+Next, create a `cypress.config.ts` file and add the following content:
+
+```ts
+import { defineConfig } from 'cypress'
+ 
+export default defineConfig({
+  e2e: {
+    setupNodeEvents(on, config) {},
+  },
+})
+```
+
+## Writing Test Cases
+
+Now, use Cypress to write an E2E test case by first creating two Modern.js pages.
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+```tsx title="routes/about/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>About</h1>
+    <Link to="/">Home</Link>
+  </div>
+);
+
+export default Index;
+```
+
+Next, create the test case file:
+
+```ts title="cypress/e2e/app.cy.ts"
+describe('Navigation', () => {
+  it('should navigate to the about page', () => {
+    // Start from the index page
+    cy.visit('http://localhost:8080/')
+ 
+    // Find a link with an href attribute containing "about" and click it
+    cy.get('a[href*="about"]').click()
+ 
+    // The new url should include "/about"
+    cy.url().should('include', '/about')
+ 
+    // The new page should contain an h1 with "About"
+    cy.get('h1').contains('About')
+  })
+})
+```
+
+The test file may lack type definitions for the API. You can refer to the [Cypress - Typescript](https://docs.cypress.io/guides/tooling/typescript-support#Configure-tsconfigjson) documentation to resolve this.
+
+You can add the command to your `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "cypress open"
+  }
+}
+```
+
+## Run Test Cases
+
+Execute the above `test` command to run the test cases:
+
+```bash
+DevTools listening on ws://127.0.0.1:55203/devtools/browser/xxxxx
+```
+
+Cypress will open a headless browser. Following the prompts, you can find the corresponding test files and automatically run the E2E tests:
+
+![cypress](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/cypress.jpg)

package/docs/en/guides/basic-features/testing/jest.mdx

@@ -0,0 +1,148 @@
+# Jest
+
+Jest is a JavaScript testing framework that is primarily used with React Testing Library for unit testing and Snapshot testing.
+
+To use Jest in Modern.js, you need to install the dependencies first. You can run the following commands:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{
+  npm: "npm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
+  yarn: "yarn add -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom",
+  pnpm: "pnpm install -D jest jest-environment-jsdom @testing-library/react @testing-library/dom @testing-library/jest-dom"
+}} />
+
+Next, you can run the following commands to automatically initialize Jest in your project and generate a basic `jest.config.ts` configuration:
+
+<PackageManagerTabs command={{
+  npm: "npm init jest@latest",
+  yarn: "yarn create jest@latest",
+  pnpm: "pnpm create jest@latest"
+}} />
+
+## Configuration File
+
+:::note
+This section will use `.ts` files for Jest testing.
+:::
+
+Compared to other testing frameworks, Jest requires more configuration at the build level, such as handling JSX and ESM syntax. Therefore, you need to install some additional dependencies:
+
+<PackageManagerTabs command={{
+  npm: "npm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
+  yarn: "yarn add -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript",
+  pnpm: "pnpm install -D babel-jest @babel/core @babel/preset-env @babel/preset-react @babel/preset-typescript"
+}} />
+
+### Configure Jest
+
+You need to further configure the `jest.config.ts` file to allow Jest to correctly compile and run test cases. Here is a basic configuration:
+
+```ts title="jest.config.ts"
+import type { Config } from 'jest';
+
+const config: Config = {
+  coverageProvider: 'babel',
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(js|jsx|ts|tsx)$': 'babel-jest',
+  },
+  transformIgnorePatterns: [],
+};
+
+export default config;
+```
+
+In the configuration, the `transformIgnorePatterns` is set to an empty array, meaning that all files will be compiled. If you want to speed up the test run, you can configure it as needed.
+
+The `setupFilesAfterEnv` will be executed at startup. In `jest.setup.ts`, you can import `@testing-library/jest-dom`, which includes a set of convenient custom matchers, such as `.toBeInTheDocument()`, to make writing tests easier:
+
+```ts title="jest.setup.ts"
+import '@testing-library/jest-dom';
+```
+
+### Configure Babel
+
+You need to configure Babel to allow Jest to automatically compile JSX and other syntax. Here is a basic configuration:
+
+```js title="babel.config.js"
+module.exports = {
+  presets: [
+    ['@babel/preset-env', { targets: { node: 'current' } }],
+    ['@babel/preset-react', { runtime: 'automatic' }],
+    '@babel/preset-typescript',
+  ],
+};
+```
+
+## Writing Test Cases
+
+Now, you can start writing tests. First, add a `test` command in `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "jest"
+  }
+}
+```
+
+Create a simple page for testing:
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+Add a test case to check if the page has the expected text:
+
+```tsx title="__tests__/page.test.tsx"
+import '@testing-library/jest-dom';
+import { render, screen } from '@testing-library/react';
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import Page from '../routes/page';
+
+describe('Page', () => {
+  it('renders a heading', () => {
+    render(
+      <Router>
+        <Page />
+      </Router>,
+    );
+
+    const heading = screen.getByRole('heading', { level: 1 });
+
+    expect(heading).toBeInTheDocument();
+  });
+});
+```
+
+In the above test case, we imported the `<Router>` component from `@modern-js/runtime/router` because React Router requires the corresponding context when rendering some route-related components.
+
+:::note
+When running directly in the Modern.js application, the `<Router>` component will be automatically injected.
+:::
+
+## Run Test Cases
+
+Execute the above `test` command to run the test cases:
+
+```bash
+ PASS  src/__tests__/page.test.tsx
+  Page
+    ✓ renders a heading (31 ms)
+
+Test Suites: 1 passed, 1 total
+Tests:       1 passed, 1 total
+Snapshots:   0 total
+Time:        0.959 s, estimated 1 s
+```