npm - @modern-js/main-doc - Versions diffs - 2.58.3 → 2.60.0 - Mend

@modern-js/main-doc 2.58.3 → 2.60.0

Files changed (203) hide show

package/docs/en/guides/advanced-features/eslint.mdx DELETED Viewed

@@ -1,148 +0,0 @@
----
-sidebar_position: 8
----
-# ESLint Rules
-**Modern.js ESLint Rules** is the full set of **ESLint** rules, includes `@modern-js` (Lint rules for Node.js projects) and `@modern-js-app` (Lint rules for web projects).
-More ESLint usage is described below with specific questions.
-## Q: How To Deal With Lint
-### Automatic Fix
-Most problems will be solved by the automatic fix of ESLint rules or the code formatting of [Prettier](https://prettier.io/) (which has been integrated into ESLint), and the developer does not need to care about the details of the problem and how to solve it.
-:::info
-This kind of automatic fix is mainly performed when the IDE saves the file, and a few will be automatically fix on submit.
-:::
-### Batch Automatic Fix
-In rare cases, such as when an old project is migrated, the following commands can be executed to repair and inspect all files in bulk:
-```bash
-pnpm run lint:error
-```
-### Manual Fix
-For problems that cannot be automatically fixed, you can click the rule link in the problem prompt box in the IDE to open the document of this rule to view the explanation and solution of the problem.
-### Claim Exceptions
-At this stage, some rules are not smart enough, and in most cases there will be great benefits, and in a few cases it may not apply. But if the entire rule is turned off or changed for these few cases, the gain is not worth the loss.
-In this case, you can use the [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) comment to mark the code blocks that meet the **rare case**, stating that this is an exception and should be ignored. For example:
-```js
-/* eslint-disable filenames/match-exported */
-...
-/* eslint-enable filenames/match-exported */
-```
-:::info
-Enter eslint in the VS Code editor, a prompt box about `eslint-disable` will automatically appear, select the prompt option to generate the corresponding comment pair.
-:::
-[Modern.js ESLint Rule Set] requires that [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules) must be used in pairs, the scope to be affected must be clearly expressed, and what rules to disable within this scope must be clearly expressed, the purpose is to make **exceptions** Clear, minimized scope to avoid abuse of [eslint-disable](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules), resulting in code that does not belong to the exception being disabled by the rule.
-## Q: How to customize ESLint rules
-### The `eslintConfig` field in `package.json` in the root directory
-This place is the default ESLint configuration for the entire repository and is designed for pure Node.js code (which can only run in Node.js).
-If the project does have special requirements or inevitable compatibility issues with some rules (not exceptions), you can add rule configuration here. This configuration will take precedence over the default [Modern.js ESLint ruleset], such as:
-```json
- "eslintConfig": {
-    "extends": [
-      "@modern-js"
-    ],
-    "rules": {
-      "filenames/match-exported": "off"
-    }
-  },
-```
-### `src/.eslintrc.js`
-Modern.js Framework or Modern.js Module project will have this configuration file by default in the source code directory, which is designed for Universal JS code.
-:::info
-Universal JS code is code that can run on both the browser side and the server side.
-:::
-If the project does have special requirements or inevitable compatibility issues with some rules (not exceptions), you can add a rule configuration here, which will take precedence over the default [Modern.js ESLint ruleset], such as:
-```js
-// eslint-disable-next-line import/no-commonjs
-module.exports = {
-  root: true,
-  extends: ['@modern-js-app'],
-  parserOptions: {
-    tsconfigRootDir: __dirname,
-    project: ['../tsconfig.json'],
-  },
-  rules: {
-    'filenames/match-exported': 'off',
-  },
-};
-```
-If necessary, you can continue to add the `.eslintrc.js` file in different subdirectories, and make special configuration for the code in this subdirectory:
-```js
-module.exports = {
-  rules: {
-    'filenames/match-exported': 'off',
-  },
-};
-```
-:::tip
-Note: It is not necessary to use the `extends` field, it will automatically inherit the configuration of the parent directory.
-:::
-### `eslintIgnore` field in `package.json`
-Adding directories that contain `.js`, `.jsx`, `.ts`, `.tsx` files, but do not require code inspection and automatic repair, to `eslintIgnore` can optimize the speed of ESLint inspection, such as:
-```json
- "eslintIgnore": [
-    "node_modules",
-    "dist",
-    "output"
-  ],
-```
-## Q: How to upgrade the version of the ESLint plugin
-As long as it is not a change in the Major version (the "^" symbol that does not comply with the [Semver](https://semver.org/) rule), you can specify this dependency directly in the `package.json` of the business project, delete the Lock file (or try to manually delete the Lock file). the contents of this package name in the file), execute `pnpm install` to reinstall the dependency and generate a new Lock file.
-After doing this, the plugin should only exist in the `./node_modules` directory of the business project and be upgraded to the version you specified.
-:::tip
-- Major version is the major version number. For more information, please read [[Semantic Versioning](https://semver.org/#summary) ].
-- All upstream projects encapsulated by Modern.js (such as ESLint, [ESLint plugin](https://eslint.org/docs/user-guide/configuring/plugins#plugins), [React Router](https://reactrouter.com/), etc.) can also be upgraded in this way.
-- Modern.js will also try to upgrade these upstream dependencies as timely as possible in each release.
-- Major version upgrades need to be published by Modern.js.
-:::
-## Q: WebStorm sometimes reports ESLint errors
-Since WebStorm believes that the ESLint execution directory is determined based on the `.eslintrc'` file. Therefore, the placement of the `src/.eslintrc` file location will cause the location specified by the `tsconfig.json` file (in the project root directory) to not be found in the'src/'directory.
-you need to configure it manually:
-```json
---parser-options=project:../tsconfig.json
-```
-![webstorm-lint-error](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/webstorm-lint-error.png)

package/docs/en/guides/advanced-features/ssg.mdx DELETED Viewed

@@ -1,116 +0,0 @@
----
-sidebar_position: 5
----
-# Static Site Generation
-SSG (Static Site Generation) is a solution based on data and templates that renders complete static web pages during the build process.
-First need to execute `pnpm run new` to enable the SSG feature:
-```bash
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable SSG
-```
-Register the SSG plugin in `modern.config.ts` after executing the command:
-```ts title="modern.config.ts"
-import { ssgPlugin } from '@modern-js/plugin-ssg';
-export default defineConfig({
-  output: {
-    ssg: true,
-  },
-  plugins: [..., ssgPlugin()],
-});
-```
-The usage of SSG differs between the **Conventional Routing** and **Self-controlled Routing**.
-### Using with Conventional Routing
-In the Conventional Routing of Modern.js, the framework generates routes based on the file structure under the entry point, so it can collect complete routing information.
-For example, here is a project directory structure that uses conventional routing:
-```bash
-.
-├── src
-│   └── routes
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── user
-│           ├── layout.tsx
-│           ├── page.tsx
-│           └── profile
-│               └── page.tsx
-```
-The above file directory will generate the following three routes:
-- `/`
-- `/user`
-- `/user/profile`
-:::note
-If you are not familiar with the rules of Conventional Routing, you can first check [Routing](/guides/basic-features/routes).
-:::
-Add component code in `src/routes/page.tsx`:
-```jsx title="src/routes/page.tsx"
-export default () => {
-  return <div>Index Page</div>;
-};
-```
-SSG also renders pages in a Node.js environment, so we can **enable SSR during development** to expose code issues and validate SSG rendering effects in advance:
-```ts title="modern.config.ts"
-export default defineConfig({
-  server: {
-    ssr: process.env.NODE_ENV === 'development',
-  }
-}
-```
-Execute the `pnpm run dev` command in the project to view the `dist/` directory, and only generate an HTML file `main/index.html`.
-Execute the `pnpm run build` command in the root path of the project. After the construction is completed, view the `dist/` directory, and generate `main/index.html`, `main/user/index.html` and `main/user/profile/index.html` three HTML files, the content corresponds to the above three routes.
-Each route in the **Conventional Routing** will generate a separate HTML file. By viewing `main/index.html`, you can find the text content that includes the `Index Page`, which is exactly the effect of SSG.
-After executing `pnpm run serve` to start the project, visit the page in the Network, view the document returned by the request. The document contains the complete page content rendered by the component.
-### Using with Self-controlled Routing
-**Self-controlled routing** is a routing through component code, which requires the application to run to obtain accurate routing information. Therefore, the SSG function cannot be used out of the box. At this time, users needs to inform the Modern.js framework in advance which routes need to enable SSG.
-For example, there is the following code which contains multiple routes. When setting `output.ssg` to `true`, only the entry route '/' will be rendered by default:
-import SelfRouteExample from '@site-docs/components/self-route-example';
-<SelfRouteExample />
-We can configure `output.ssg` to inform Modern.js to enable SSG for specific routes, such as `/about`:
-```ts title="modern.config.ts"
-export default defineConfig({
-  output: {
-    ssg: {
-      routes: ['/', '/about'],
-    },
-  },
-});
-```
-After executing `pnpm run build` and `pnpm run serve`, you can access `http://localhost:8080/about` to see the rendered page in preview.
-You can check the bundle file that a new `main/about/index.html` file has been added to the `dist/` directory.
-:::info
-Above only introduces the case of single entry, for more related content please refer to the [SSG API](/configure/app/output/ssg).
-:::

package/docs/en/guides/advanced-features/ssr/_meta.json DELETED Viewed

	@@ -1 +0,0 @@
1	- ["usage", "stream", "cache"]

package/docs/en/guides/advanced-features/ssr/index.mdx DELETED Viewed

@@ -1,23 +0,0 @@
-# SSR
-By rendering the HTML content of web pages into complete web pages on the server side, and then sending the generated web pages to the client, the client only needs to display the web pages without further rendering.
-Its main advantages are:
-- Improve first screen load speed: SSR can generate complete websites on the server side, the client only needs to download the content of the website, no additional renderings are required, thus improving the first screen load speed.
-- Improve user experience: SSR can improve the responsiveness of web pages, thereby enhancing the user experience.
-- Good for SEO: SSR can generate complete HTML content. Search engines can directly index HTML content to improve website ranking.
-If you have the following scenarios, developers can consider using SSR to render your pages:
-1. Websites with higher first-screen loading speed requirements, such as e-commerce websites, news websites, etc.
-2. Websites with higher user experience requirements, such as social networking sites, gaming sites, etc.
-3. Websites with higher SEO requirements, such as corporate websites, blogs, etc.
-In Modern.js, SSR is also out-of-the-box. Developers do not need to write complex server-side logic for SSR, nor do they need to worry about the operation and maintenance of SSR, or create separate services.
-In addition to the out-of-the-box SSR service, to ensure the developer's development experience, we also have:
-- A complete SSR downgrade strategy to ensure that the page can run safely.
-- Automatically split sub-routes to load on demand, reducing the size of the first screen resources.
-- Built-in caching system to solve the problem of high server-side load.

package/docs/en/guides/advanced-features/ssr/stream.mdx DELETED Viewed

@@ -1,248 +0,0 @@
----
-sidebar_position: 2
-title: Streaming SSR
----
-# Streaming SSR
-## Overview
-Stream rendering is a new way of rendering, which can update the page content in real time when the user interacts with the page, thereby improving the user experience.
-In traditional rendering, the rendering of the page is completed at once, while in stream rendering, the rendering of the page is gradually completed. When the user interacts with the page, data is loaded gradually instead of loading all at once.
-Compared to traditional rendering:
-- Faster perceived speed: Stream rendering can gradually display content during the rendering process to display the business home page at the fastest speed.
-- Better user experience: Through stream rendering, users can see the content on the page faster, instead of waiting for the entire page to be rendered before they can interact.
-- Better performance control: Stream rendering allows developers to better control the loading priority and order of pages, thereby optimizing performance and user experience.
-- Better adaptability: Stream rendering can better adapt to different network speeds and device performances, allowing the page to perform better in various environments.
-## Usage
-Modern.js supports streaming rendering in React 18 which can be enabled through the following configuration:
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-export default defineConfig({
-  server: {
-    ssr: {
-      mode: 'stream',
-    },
-  },
-});
-```
-The streaming SSR of Modern.js is implemented based on React Router, and the main APIs involved are:
-- [`defer`](https://reactrouter.com/en/main/utils/defer): This utility allows you to defer values returned from loaders by passing promises instead of resolved values.
-- [`Await`](https://reactrouter.com/en/main/components/await): Used to render deferred values with automatic error handling.
-- [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value): Returns the resolved data from the nearest `<Await>` ancestor component.
-### Return async data
-```ts title="page.data.ts"
-import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
-interface User {
-  name: string;
-  age: number;
-}
-export interface Data {
-  data: User;
-}
-export const loader = ({ params }: LoaderFunctionArgs) => {
-  const userId = params.id;
-  const user = new Promise<User>(resolve => {
-    setTimeout(() => {
-      resolve({
-        name: `user-${userId}`,
-        age: 18,
-      });
-    }, 200);
-  });
-  return defer({ data: user });
-};
-```
-`user` is a `Promise` object that represents the data that needs to be obtained asynchronously. Use `defer` to handle the asynchronous retrieval of user. Note that `defer` must receive an object type parameter, so the parameter passed to `defer` is: `{ data: user }`.
-`defer` can receive both asynchronous and synchronous data at the same time. For example:
-```ts title="page.data.ts"
-// skip some codes
-export default ({ params }: LoaderFunctionArgs) => {
-  const userId = params.id;
-  const user = new Promise<User>(resolve => {
-    setTimeout(() => {
-      resolve({
-        name: `user-${userId}`,
-        age: 18,
-      });
-    }, 200);
-  });
-  const otherData = new Promise<string>(resolve => {
-    setTimeout(() => {
-      resolve('some sync data');
-    }, 200);
-  });
-  return defer({
-    data: user,
-    other: await otherData,
-  });
-};
-```
-The data obtained from otherData is synchronous because it has an `await` keyword in front of it. It can be passed into `defer` together with the asynchronous data obtained from `user`.
-### Render asynchronous data.
-With the `<Await>` component, you can retrieve the data asynchronously returned by the Data Loader and then render it. For example:
-```tsx title="page.tsx"
-import { Await, useLoaderData } from '@modern-js/runtime/router';
-import { Suspense } from 'react';
-import type { Data } from './page.data';
-const Page = () => {
-  const data = useLoaderData() as Data;
-  return (
-    <div>
-      User info:
-      <Suspense fallback={<div id="loading">loading user data ...</div>}>
-        <Await resolve={data.data}>
-          {user => {
-            return (
-              <div id="data">
-                name: {user.name}, age: {user.age}
-              </div>
-            );
-          }}
-        </Await>
-      </Suspense>
-    </div>
-  );
-};
-export default Page;
-```
-`<Await>` needs to be wrapped inside the `<Suspense>` component. The `resolve` function passed into `<Await>` is used to asynchronously retrieve data from a Data Loader. Once the data has been retrieved, it is rendered using [Render Props](https://reactjs.org/docs/render-props.html) mode. During the data retrieval phase, the content specified in the `fallback` property of `<Suspense>` will be displayed.
-:::warning Warning
-When importing types from a Data Loader file, it is necessary to use the `import type` syntax to ensure that only type information is imported. This can avoid packaging Data Loader code into the bundle file of the front-end product.
-Therefore, the import method here is: `import type { Data } from './page.data'`;
-:::
-You can also retrieve asynchronous data returned by the Data Loader using `useAsyncValue`. For example:
-```tsx title="page.tsx"
-import { useAsyncValue } from '@modern-js/runtime/router';
-// skip some codes
-const UserInfo = () => {
-  const user = useAsyncValue();
-  return (
-    <div>
-      name: {user.name}, age: {user.age}
-    </div>
-  );
-};
-const Page = () => {
-  const data = useLoaderData() as Data;
-  return (
-    <div>
-      User info:
-      <Suspense fallback={<div id="loading">loading user data ...</div>}>
-        <Await resolve={data.data}>
-          <UserInfo />
-        </Await>
-      </Suspense>
-    </div>
-  );
-};
-export default Page;
-```
-### Error handling
-The `errorElement` property of the `<Await>` component can be used to handle errors thrown when the Data Loader executes or when a child component renders.
-For example, we intentionally throw an error in the Data Loader function:
-```ts title="page.data.ts"
-import { defer } from '@modern-js/runtime/router';
-export const loader = () => {
-  const data = new Promise((resolve, reject) => {
-    setTimeout(() => {
-      reject(new Error('error occurs'));
-    }, 200);
-  });
-  return defer({ data });
-};
-```
-Then use `useAsyncError` to get the error, and assign the component used to render the error to the `errorElement` property of the `<Await>` component:
-```tsx title="page.ts"
-import { Await, useAsyncError, useLoaderData } from '@modern-js/runtime/router';
-import { Suspense } from 'react';
-export default function Page() {
-  const data = useLoaderData();
-  return (
-    <div>
-      Error page
-      <Suspense fallback={<div>loading ...</div>}>
-        <Await resolve={data.data} errorElement={<ErrorElement />}>
-          {(data: any) => {
-            return <div>never displayed</div>;
-          }}
-        </Await>
-      </Suspense>
-    </div>
-  );
-}
-function ErrorElement() {
-  const error = useAsyncError() as Error;
-  return <p>Something went wrong! {error.message}</p>;
-}
-```
-## Waiting for all content to load for spiders
-Streaming offers a better user experience because the user can see the content as it becomes available.
-However, when a spider visits your page, you might want to let all of the content load first and then produce the final HTML output instead of revealing it progressively.
-Modern.js uses [isbot](https://www.npmjs.com/package/isbot) to examine the user-agent of requests, determining whether they come from a crawler.
-:::info More
-1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
-2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
-:::
-import StreamSSRPerformance from '@site-docs/components/stream-ssr-performance';
-<StreamSSRPerformance />