@modern-js/main-doc 2.54.5 → 2.55.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/apis/app/runtime/web-server/middleware.mdx

@@ -7,12 +7,15 @@ title: Middleware
 Used to extend the built-in Web Server of Modern.js, unlike [Hook](/apis/app/runtime/web-server/hook), Middleware can directly operate Node's origin request and response, and can be extended using the framework plugin.
 
 :::note
+
 In the next major release, Modern.js will use new middleware to replace this approach.
 
 It is recommended to use [UnstableMiddleware](/apis/app/runtime/web-server/unstable_middleware) to handle page requests.
+
 :::
 
 :::note
+
 For more detail, see [Extend Web Server](/guides/advanced-features/web-server).
 
 :::

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/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

package/docs/en/guides/concept/entries.mdx

@@ -82,12 +82,13 @@ By default, Modern.js scans the files under `src/` before starting the project,
 
 :::
 
-Not all top-level directories under `src/` become project entries. The directory where the entry is located must meet one of the following four conditions:
+Not all top-level directories under `src/` become project entries. The directory where the entry is located must meet one of the following five conditions:
 
 1. Has a `routes/` directory.
 2. Has an `App.[jt]sx?` file.
 3. Has an `index.[jt]sx?` file.
 4. Has a `pages/` directory (compatible with Modern.js 1.0).
+5. Has an `entry.[jt]sx?` file.
 
 When the `src/` directory meets the entry requirements, Modern.js considers the current project as a single entry application.
 
@@ -139,8 +140,46 @@ export default () => {
 
 For more information, please refer to [Self-controlled Routing](/guides/basic-features/routes.html#self-controlled-routing).
 
+#### Custom Entry
+
+If there is an `entry.[jt]sx` file in the entry, developers need to call the `createRoot` and `render` functions in the `entry.[jt]sx` file to complete the project's entry logic.
+
+:::info
+Using this file requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
+:::
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+render(<ModernRoot />);
+```
+
+For example, if some other operations need to be performed before render is executed, it can be implemented in this way:
+
+```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 />);
+});
+```
+
 #### Custom Bootstrap
 
+:::warning
+Soon to be deprecated, it is recommended to use a custom entry.
+:::
+
 If there is an `index.[jt]sx` file in the entry, and the file exports a function by default, Modern.js will pass the default `bootstrap` function as a parameter and use the exported function to replace the default `bootstrap`. This way, developers can customize how components are mounted to DOM nodes or add custom behavior before mounting. For example:
 
 ```tsx
@@ -152,44 +191,19 @@ export default (App: React.ComponentType, bootstrap: () => void) => {
 };
 ```
 
-At this point, the generated file content of Modern.js is as follows:
-
-```js
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import customBootstrap from '@_modern_js_src/index.tsx';
-import App from '@_modern_js_src/App';
-import { router, state } from '@modern-js/runtime/plugins';
-
-const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
-const MOUNT_ID = 'root';
-
-let AppWrapper = null;
-
-function render() {
-  AppWrapper = createApp({
-    // plugin parameters for runtime...
-  })(App);
-  if (IS_BROWSER) {
-    customBootstrap(AppWrapper);
-  }
-  return AppWrapper;
-}
-
-AppWrapper = render();
-
-export default AppWrapper;
-```
-
 ### Build Mode Entry
 
-Build mode refers to the mode where the entry point of the page is not automatically generated by Modern.js, but is fully defined by the developers themselves.
+Build mode refers to not using the Runtime capabilities provided by Modern.js, but rather having the developer define the entry of the page completely on their own.
+
+When the entry directory contains `index.[jt]sx` (soon to be deprecated) and does not export a function via `export default`, or when there is an `entry.[jt]sx` file in the entry directory and the `@modern-js/runtime` dependency is not installed, the corresponding file will be identified as the entry module of webpack or Rspack.
 
-When there is an `index.[jt]sx` file in the entry directory and it is not exported as a function using `export default`, this type of file will be recognized as the entry module for webpack or Rspack.
+:::info
+Using the `entry.[jt]sx` file requires enabling [source.enableCustomEntry](/configure/app/source/enable-custom-entry).
+:::
 
 In this case, Modern.js will not generate the entry code automatically. Therefore, you need to manually mount the component to the DOM node, for example:
 
-```js title=src/index.jsx
+```js title=src/entry.tsx
 import React from 'react';
 import ReactDOM from 'react-dom';
 import App from './App';
@@ -197,9 +211,9 @@ import App from './App';
 ReactDOM.render(<App />, document.getElementById('root'));
 ```
 
-This approach is equivalent to enabling the [source.entries.disableMount](/configure/app/source/entries) option in Modern.js. When you use this approach, **you will not be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the modern.config.js file will no longer take effect.
+This approach is equivalent to enabling the [source.entries.disableMount](/configure/app/source/entries) option in Modern.js. When you use this approach, **you will not be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the `modern.config.js` file will no longer take effect.
 
-## Custom Entries
+## Custom Entries Config
 
 In some cases, you may need to customize the entry configuration instead of using the entry conventions provided by Modern.js.
 
@@ -232,4 +246,4 @@ export default defineConfig({
 });
 ```
 
-Note that when you enable `disableMount`, **you won't be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the modern.config.ts file.
+Note that when you enable `disableMount`, **you won't be able to use the runtime capabilities of the Modern.js framework**, such as the `runtime` configuration in the `modern.config.ts` file.