@modern-js/main-doc 2.54.6 → 2.56.0

package/docs/en/apis/app/hooks/src/entry.mdx

@@ -0,0 +1,42 @@
+---
+title: entry.[tj]s
+sidebar_position: 4
+---
+# entry.[tj]s
+
+:::info
+Using this file requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
+:::
+
+Normally, the [`routes/`](/apis/app/hooks/src/routes.html) and [`App.[tj]sx`](/apis/app/hooks/src/app) hook files can meet our needs. When we need to add custom behavior before component rendering or take full control of the webpack packaging entry, we can create `entry.[tj]s` file in the src or entry directory. Here are two cases for discussion:
+
+## Add custom behavior before Render
+
+This is implemented in `src/entry.[tj]s` as follows:
+
+```js title=src/entry.tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+   // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+
+## Take full control of the webpack entry
+
+When the project does not install the `@modern-js/runtime` dependency, `src/entry.[tj]sx?` is the real webpack packaging entry file, and you can directly organize the code like using create-react-app and other scaffolds:
+
+```js title=src/entry.jsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```

package/docs/en/apis/app/hooks/src/entry.server.mdx

@@ -0,0 +1,52 @@
+---
+title: entry.server.[tj]sx
+sidebar_position: 5
+---
+
+# entry.server.[tj]sx
+
+When the project initiates `server.ssr`, Modern.js generates a default Server-Side entry. The sample code is as follows:
+
+```tsx title="entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## Add Custom Entry Points
+
+Users need to customize the Server-Side Rendering entry points, they can customize the server entry in `src/entry.server.ts` or `src/{entryName}/entry.server.ts`.
+
+```tsx title="src/entry.server.tsx"
+import { renderString, createRequestHandler } from '@edenx/runtime/ssr/server';
+import type { HandleRequest } from '@edenx/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  // do something before rendering
+  const body = await renderString(request, <ServerRoot />, options);
+
+  const newBody = body + '<div>Byte-Dance</div>';
+
+  return new Response(newBody, {
+    headers: {
+      'content-type': 'text/html; charset=UTF-8',
+      'x-custom-header': 'abc',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/en/apis/app/hooks/src/index_.mdx

@@ -4,6 +4,10 @@ sidebar_position: 4
 ---
 # index.[tj]s
 
+:::warning
+Soon to be deprecated, it is recommended to use [`entry.[tj]s`](/apis/app/hooks/src/entry)。
+:::
+
 The identifier for the entry point when the application uses custom `bootstrap`.
 
 In general, the [`App.[tj]sx`](/apis/app/hooks/src/app) hook file can already meet our needs. When we need to add custom behavior before `bootstrap` or completely take over the webpack packaging entry, we can place `index.[tj]s` in the `src` or entry directory. There are two cases below:

package/docs/en/apis/app/runtime/core/bootstrap.mdx

@@ -3,6 +3,10 @@ title: bootstrap
 ---
 # bootstrap
 
+:::warning
+Soon to be deprecated, it is recommended to use [`render`](/apis/app/runtime/core/render).
+:::
+
 Used to start and mount App, usually not manually called. This API is only required when using [Custom Bootstrap](/guides/concept/entries#custom-bootstrap).
 
 ## Usage

package/docs/en/apis/app/runtime/core/create-app.mdx

@@ -3,7 +3,11 @@ title: createApp
 ---
 # createApp
 
-Used to create custom entries, custom runtime plugins. This API is only required when using [Custom App](/guides/concept/entries#app).
+:::warning
+Soon to be deprecated, it is recommended to use [`createRoot`](/apis/app/runtime/core/create-root).
+:::
+
+Used for creating custom entries and customizing runtime plugins.
 
 ## Usage
 

package/docs/en/apis/app/runtime/core/create-root.mdx

@@ -0,0 +1,22 @@
+---
+title: createRoot
+---
+# createRoot
+
+It is used to create the root component provided by Modern.js, which will automatically register Runtime plugins and complete the initialization of Runtime plugins.
+
+## Usage
+
+```ts
+import { createRoot } from '@modern-js/runtime/react';
+```
+
+## Function Signature
+
+```ts
+export function createRoot(UserApp?: React.ComponentType | null): React.ComponentType<any>;
+```
+
+### Parameters
+
+- `UserApp`: an optional parameter, and the default is the component exported from `App.tsx`.

package/docs/en/apis/app/runtime/core/render.mdx

@@ -0,0 +1,42 @@
+---
+title: render
+---
+# render
+
+It is used to render project components.
+
+## Usage
+
+```ts
+import { render } from '@modern-js/runtime/browser';
+
+render(<ModernRoot />);
+```
+
+## Function Signature
+
+```ts
+export function render(App: React.ReactElement, id?: HTMLElement | string): Promise<any>;
+```
+
+### Parameters
+
+- `App`：An instance of ReactElement created through [`createRoot`](./create-root).
+- `id`：The id of the DOM root element to be mounted, such as "root".
+
+## Example
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+   // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```

package/docs/en/apis/app/runtime/ssr/renderStreaming.mdx

@@ -0,0 +1,69 @@
+---
+title: renderStreaming
+---
+
+# renderStreaming
+
+Used for React v18+ Streaming SSR to render readable streams, used in conjunction with `createRequestHandler`.
+
+## Usage
+
+```ts title="src/entry.server.tsx"
+import {
+  renderStreaming,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  const stream = await renderStreaming(request, <ServerRoot />, options);
+
+  return new Response(stream, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## Function Signature
+
+```ts
+export type RenderStreaming = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<ReadableStream>;
+```
+
+## Example
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderStreaming,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  // do something before render
+  const stream = await renderStreaming(request, <ServerRoot />, options);
+
+  // docs: https://developer.mozilla.org/en-US/docs/Web/API/TransformStream
+  const transformStream = new TransformStream({
+    transform(chunk, controller) {
+      // do some transform
+    },
+  });
+
+  stream.pipeThrough(transformStream);
+
+  return new Response(transformStream.readable, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/en/apis/app/runtime/ssr/renderString.mdx

@@ -0,0 +1,62 @@
+---
+title: renderString
+---
+
+# renderString
+
+Used for React String SSR to render strings, used in conjunction with `createRequestHandler`.
+
+## Usage
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## Function Signature
+
+```ts
+export type RenderString = (
+  request: Request,
+  serverRoot: React.ReactElement,
+  optinos: RenderOptions,
+) => Promise<string>;
+```
+
+## Example
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  // do something before render
+  const body = await renderString(request, <ServerRoot />, options);
+
+  const newBody = body + '<div>Byte-Dance</div>';
+
+  return new Response(newBody, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/en/apis/app/runtime/ssr/requestHandler.mdx

@@ -0,0 +1,47 @@
+---
+title: createRequestHandler
+---
+
+# createRequestHandler
+
+Used to customize the Server-Side Rendering entry to return the `requestHandler`.
+
+## Usage
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## Function Signature
+
+```ts
+export type HandleRequest = (
+  request: Request,
+  ServerRoot: React.ComponentType,
+  options: HandleRequestOptions,
+) => Promise<Response>;
+
+export type RequestHandler = (
+  request: Request,
+  options: RequestHandlerOptions,
+) => Promise<Response>;
+
+export type CreateRequestHandler = (
+  handleRequest: HandleRequest,
+) => Promise<RequestHandler>;
+```

package/docs/en/components/debug-app.mdx

@@ -2,11 +2,11 @@ Run `pnpm run dev` in the project to start the project:
 
 ```bash
 $ pnpm run dev
-
 > modern dev
 
-info    Starting dev server...
-ready   Client compiled in 50 ms
+  Modern.js Framework v2.55.0
+
+ready   Client compiled in 0.86 s
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

package/docs/en/configure/app/dev/live-reload.mdx

@@ -0,0 +1,27 @@
+---
+sidebar_label: liveReload
+---
+
+# dev.liveReload
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to reload the page when source files are changed.
+
+By default, Modern.js uses HMR as the preferred method to update modules. If HMR is disabled or cannot be used in certain scenarios, it will automatically fallback to liveReload.
+
+Please refer to [Hot Module Replacement](https://rsbuild.dev/guide/advanced/hmr) for more information.
+
+## Disabling liveReload
+
+If you need to disable liveReload, you can set both `dev.hmr` and `dev.liveReload` to `false`. Then, no Web Socket requests will be made to the dev server on the page, and the page will not automatically refresh when file change.
+
+```js
+export default {
+  dev: {
+    hmr: false,
+    liveReload: false,
+  },
+};
+```

package/docs/en/configure/app/dev/setup-middlewares.mdx

@@ -0,0 +1,69 @@
+---
+sidebar_label: setupMiddlewares
+---
+
+# dev.setupMiddlewares
+
+- **Type:**
+
+```ts
+type ServerAPIs = {
+  sockWrite: (
+    type: string,
+    data?: string | boolean | Record<string, any>,
+  ) => void;
+};
+
+type SetupMiddlewares = Array<
+  (
+    middlewares: {
+      unshift: (...handlers: RequestHandler[]) => void;
+      push: (...handlers: RequestHandler[]) => void;
+    },
+    server: ServerAPIs,
+  ) => void
+>;
+```
+
+- **Default:** `undefined`
+
+Provides the ability to execute a custom function and apply custom middlewares.
+
+The order among several different types of middleware is: `unshift` => internal middlewares => `push`.
+
+```js
+export default {
+  dev: {
+    setupMiddlewares: [
+      (middlewares, server) => {
+        middlewares.unshift((req, res, next) => {
+          next();
+        });
+
+        middlewares.push((req, res, next) => {
+          next();
+        });
+      },
+    ],
+  },
+};
+```
+
+It is possible to use some server api to meet special scenario requirements:
+
+- sockWrite. Allow send some message to HMR client, and then the HMR client will take different actions depending on the message type. If you send a "content changed" message, the page will reload.
+
+```js
+export default {
+  dev: {
+    setupMiddlewares: [
+      (middlewares, server) => {
+        // add custom watch & trigger page reload when change
+        watcher.on('change', (changed) => {
+          server.sockWrite('content-changed');
+        });
+      },
+    ],
+  },
+};
+```

package/docs/en/configure/app/dev/watch-files.mdx

@@ -0,0 +1,59 @@
+---
+sidebar_label: watchFiles
+---
+
+# dev.watchFiles
+
+- **Type:**
+
+```ts
+type WatchFiles = {
+  paths: string | string[];
+  // watch options for chokidar
+  options?: WatchOptions;
+};
+```
+
+- **Default:** `undefined`
+
+Watch files and directories for changes. When a file changes, the page will be reloaded.
+
+If both `dev.hmr` and `dev.liveReload` are set to false, `watchFiles` will be ignored.
+
+:::tip
+When files in WatchFiles change, reloading and recompilation of the configuration file will not be triggered.
+:::
+
+### Example
+
+You can configure a list of globs/directories/files to watch for file changes.
+
+```js
+export default {
+  dev: {
+    watchFiles: {
+      // watch a single file
+      paths: 'public/demo.txt',
+      // use a glob pattern
+      paths: 'src/**/*.txt',
+      // watch multiple file paths
+      paths: ['src/**/*.txt', 'public/**/*'],
+    },
+  },
+};
+```
+
+You can also specify [chokidar](https://github.com/paulmillr/chokidar#api) watcher options by passing an object with `paths` and `options` properties.
+
+```js
+export default {
+  dev: {
+    watchFiles: {
+      paths: 'src/**/*.txt',
+      options: {
+        usePolling: false,
+      },
+    },
+  },
+};
+```

package/docs/en/configure/app/dev/write-to-disk.mdx

@@ -0,0 +1,38 @@
+---
+sidebar_label: writeToDisk
+---
+
+# dev.writeToDisk
+
+- **Type:** `boolean | ((filename: string) => boolean)`
+- **Default:** `(file) => !file.includes('.hot-update.')`
+
+Used to control whether the build artifacts of the development environment are written to the disk.
+
+## Writing to Memory
+
+You can choose to save the build artifacts in the memory of the dev server, thereby reducing the overhead caused by file operations.
+
+Simply set the `dev.writeToDisk` option to `false`:
+
+```ts
+export default {
+  dev: {
+    writeToDisk: false,
+  },
+};
+```
+
+## Matching Specific Files
+
+You can also set `dev.writeToDisk` to a function to match only certain files. When the function returns `false`, the file will not be written; when it returns `true`, the file will be written to disk.
+
+For example, Modern.js by default write files to disk while excluding hot-update temporary files:
+
+```ts
+export default {
+  dev: {
+    writeToDisk: (file) => !file.includes('.hot-update.'),
+  },
+};
+```

package/docs/en/configure/app/output/ssg.mdx

@@ -9,6 +9,10 @@ sidebar_label: ssg
 
 Enable the SSG for **Self-controlled Routing** or **Conventional Routing**.
 
+:::info Enable SSG
+This configuration will only be available when the SSG feature is enabled. Please read the [Static Site Generation](/guides/advanced-features/ssg) documentation to learn how to enable the SSG feature.
+:::
+
 :::info
 For more routes detail, see [Routing](/guides/basic-features/routes).
 

package/docs/en/configure/app/source/enable-async-entry.mdx

@@ -35,15 +35,15 @@ Then run the `dev` or `build` command, and you will see that the files automatic
 node_modules
   └─ .modern-js
      └─ main
-        ├─ bootstrap.jsx  #  real entry code
-        ├─ index.js      # asynchronous entry file
+        ├─ bootstrap.jsx  # asynchronous entry file
+        ├─ index.js      # real entry code
         └─ index.html
 ```
 
-The contents of `index.js` are as follows:
+The contents of `bootstrap.js` are as follows:
 
 ```js
-import('./bootstrap.jsx');
+import('./index.jsx');
 ```
 
 At this point, you can consume any remote module in the current page.

package/docs/en/configure/app/source/enable-custom-entry.mdx

@@ -0,0 +1,41 @@
+---
+sidebar_label: enableCustomEntry
+---
+
+# source.enableCustomEntry
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+This option is used for custom Modern.js entries.
+
+When this option is enabled, Modern.js will use the `src/entry.[jt]sx` file as the project's entry point. For more details, refer to [Entries](/guides/concept/entries.html).
+
+## Example
+
+First, enable this option in the configuration file:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    enableCustomEntry: true,
+  },
+});
+```
+
+Create the `src/entry.tsx` file:
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+   // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```

package/docs/en/guides/advanced-features/ssr/cache.mdx

@@ -53,10 +53,10 @@ In this, customKey is used for custom cache key. By default, Modern.js will use
 ```ts
 export type CacheOptionProvider = (
   req: IncomingMessage,
-) => Promise<CacheControl> | CacheControl;
+) => Promise<CacheControl | false> | CacheControl | false;
 ```
 
-Sometimes developers need to customise the cache key through req, which can be handled using the function form, as shown in the following code:
+Sometimes developers need to customise the cache key through req or when caching does not work for specific URLs, which can be handled using the function form, as shown in the following code:
 
 ```ts title="server/cache.ts"
 import type { CacheOption, CacheOptionProvider } from '@modern-js/runtime/server';
@@ -66,6 +66,11 @@ const provider: CacheOptionProvider = (req) => {
 
   const key = computedKey(url, headers, ...);
 
+  if(url.includes('no-cache=1')) {
+    return false;
+  }
+
+
   return {
     maxAge: 500, // ms
     staleWhileRevalidate: 1000, // ms