@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.97 → 3.5.0-ultramodern.99

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

@@ -0,0 +1,39 @@
+---
+title: entry.ts
+sidebar_position: 4
+---
+
+# entry.tsx
+
+Normally, the [`routes/`](/apis/app/hooks/src/routes.html) and [`App.tsx`](/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 Rspack packaging entry, we can create `entry.ts` file in the src or entry directory. Here are two cases for discussion。
+
+## Add custom behavior before Render
+
+This is implemented in `src/entry.ts` 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 Rspack entry
+
+When the project does not install the `@modern-js/runtime` dependency, `src/entry.tsx?` is the real Rspack 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/apis/app/hooks/src/entry.server.mdx

@@ -0,0 +1,56 @@
+---
+title: entry.server.tsx
+sidebar_position: 5
+---
+
+# entry.server.tsx
+
+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,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: 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,
+  type HandleRequest,
+} from '@modern-js/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/apis/app/hooks/src/modern.runtime.mdx

@@ -0,0 +1,9 @@
+---
+title: modern.runtime.ts
+sidebar_position: 4
+---
+# modern.runtime.ts
+
+The Modern.js Runtime configuration file allows for personalized configuration of the Runtime capabilities for the current project.
+
+For specific usage of the configuration, please refer to [Runtime Configuration](/configure/app/runtime/0-intro.html).

package/docs/apis/app/hooks/src/routes.mdx

@@ -0,0 +1,90 @@
+---
+title: routes/
+sidebar_position: 2
+---
+# routes/
+
+The identifier for the entry point when the application uses [Conventional Routing](/guides/basic-features/routes/routes#conventional-routing).
+
+Conventional routing uses `routes/` as the convention for the entry point and analyzes the files in the `src/routes` directory to obtain the client-side routing configuration.
+
+Any `layout.tsx` and `page.tsx` under `src/routes` will be used as the application's routes:
+
+```bash
+.
+└── routes
+    ├── layout.tsx  # [!code highlight]
+    ├── page.tsx # [!code highlight]
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+## Basic Example
+
+The directory name under `routes` will be used as the mapping of the route URL. `layout.tsx` is used as the layout component and `page.tsx` is used as the content component in the routing. They are the leaf nodes of the entire route. For example, the following directory structure:
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+will generate two routes:
+
+- `/`
+- `/user`
+
+## Dynamic Routing
+
+If the directory name of the route file is named with `[]`, the generated route will be used as a dynamic route. For example, the following file directory:
+
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+The `routes/[id]/page.tsx` file will be converted to the `/:id` route. Except for the `/blog` route that can be matched exactly, all other `/xxx` routes will be matched to this route.
+
+In the component, you can use [useParams](/apis/app/runtime/router/router#useparams) to obtain the corresponding named parameter.
+
+When using the [loader](/guides/basic-features/data/data-fetch#the-loader-function) function to obtain data, `params` will be passed as an input parameter to the `loader` function, and the corresponding parameter can be obtained through the attribute of `params`.
+
+## Layout Component
+
+In the following example, a common layout component can be added to all route components by adding `layout.tsx`:
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+In the layout component, you can use `<Outlet>` to represent the child components:
+
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  );
+};
+```
+
+:::note
+`<Outlet>` is an API provided by React Router. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+
+:::

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

@@ -0,0 +1,7 @@
+---
+title: '*.[server|node].tsx'
+sidebar_position: 8
+---
+# *.[server|node].tsx
+
+Used in the application project to place server-side code. When `*.tsx` and `*.[server|node].tsx` coexist, SSR will prefer to use the `*.[server|node].tsx` file instead of the `*.tsx` file when rendering on the server.

package/docs/apis/app/runtime/_meta.json

@@ -0,0 +1,32 @@
+[
+  {
+    "type": "dir",
+    "name": "core",
+    "label": "Core",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "router",
+    "label": "Router",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "ssr",
+    "label": "SSR",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "bff",
+    "label": "BFF",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "utility",
+    "label": "Utility",
+    "collapsed": true
+  }
+]

package/docs/apis/app/runtime/bff/use-backend-context.mdx

@@ -0,0 +1,30 @@
+---
+title: useHonoContext
+---
+# useHonoContext
+
+Used to obtain backend request context in an integrated BFF function.
+
+## Usage
+
+```ts
+import { useHonoContext } from '@modern-js/server-runtime';
+```
+
+## Function Signature
+
+`function useHonoContext(): Context`
+
+## Example
+
+Developers can use `context` to obtain more request information, such as setting response headers:
+
+```ts
+import { useHonoContext } from '@modern-js/server-runtime';
+
+export async function get() {
+  const c = useHonoContext();
+  c.res.headers.set('x-bff-api', 'true');
+  // ...
+}
+```

package/docs/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/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/apis/app/runtime/core/runtime-context.mdx

@@ -0,0 +1,160 @@
+---
+title: RuntimeContext
+---
+# RuntimeContext
+
+`RuntimeContext` is a React Context used to get Runtime context information in components. This Context can be accessed through React's `use` or `useContext` API.
+
+:::warning
+
+The `useRuntimeContext` Hook has been deprecated. Please use `use(RuntimeContext)` instead. `useRuntimeContext` is internally implemented as `useContext(RuntimeContext)`, while `use(RuntimeContext)` is the recommended new approach in React 19.
+
+:::
+
+## Usage
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+export function App() {
+  const runtimeContext = use(RuntimeContext); // You can also use useContext(RuntimeContext)
+  return <div>Hello World</div>
+}
+```
+
+## Type Definition
+
+```ts
+type TRuntimeContext = {
+  initialData?: Record<string, unknown>;
+  isBrowser: boolean;
+  routes?: RouteObject[];
+  requestContext: RequestContext;
+  /**
+   * @deprecated Use `requestContext` instead
+   */
+  context: RequestContext;
+  [key: string]: unknown;
+};
+```
+
+### Property Description
+
+- `isBrowser`: Indicates whether the current runtime environment is a browser
+- `routes`: Route configuration information
+- `requestContext`: Request context, containing `request` and `response` objects
+- `context`: Deprecated, please use `requestContext` instead
+
+### RequestContext
+
+`RequestContext` is the type of the `requestContext` property, containing request and response related information:
+
+```ts
+type RequestContext = {
+  request: {
+    params: Record<string, string>;      // Route parameters
+    pathname: string;                     // Pathname
+    query: Record<string, string>;        // Query parameters
+    headers: IncomingHttpHeaders;         // Request headers
+    host: string;                         // Hostname
+    url: string;                          // Full URL
+    referer?: string;                     // Referrer page
+    userAgent?: string;                   // User agent
+    cookie?: string;                      // Cookie string
+    cookieMap?: Record<string, string>;   // Cookie map object
+  };
+  response: {
+    setHeader: (key: string, value: string) => void;  // Set response header (server-side only)
+    status: (code: number) => void;                   // Set status code (server-side only)
+    locals: Record<string, any>;                      // Local data
+  };
+};
+```
+
+**Notes**:
+
+- `response.setHeader` and `response.status` are only available on the server-side (SSR)
+- On the browser side, the `response` object may not contain these methods
+- The `request` object is available on both server and browser, but server-side information is more complete
+
+## Usage Examples
+
+### Distinguishing Runtime Environment
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const { context, isBrowser } = use(RuntimeContext);
+
+  if (isBrowser === true) {
+    // Browser-side execution logic
+    console.log('browser render')
+  } else {
+    // Server-side execution logic
+    // Note: Functions like logger need to be injected into context through Runtime plugins
+    console.log('server render')
+  }
+}
+```
+
+### Getting Request Context
+
+When SSR is enabled, isomorphic request context can be obtained in both Node environment and browser environment.
+
+The slight difference is that the Node environment also supports setting response headers, response codes, and provides Logger logging and Metrics tracking.
+
+:::tip
+
+When SSR is not enabled, only the information that can be obtained on the browser side is included.
+
+:::
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const runtimeContext = use(RuntimeContext);
+  const { request, response } = runtimeContext.requestContext || {};
+
+  // Access request information
+  const userAgent = request?.userAgent || request?.headers?.['user-agent'];
+  const url = request?.url;
+  const query = request?.query;
+  const params = request?.params;
+
+  // Server-side can set response headers
+  if (!runtimeContext.isBrowser && response) {
+    response.setHeader('X-Custom-Header', 'value');
+    response.status(200);
+  }
+
+  return (
+    <div>
+      <div>User Agent: {userAgent}</div>
+      <div>URL: {url}</div>
+      <div>Query: {JSON.stringify(query)}</div>
+    </div>
+  );
+}
+```
+
+### Accessing Injected Global Data
+
+Global data can be injected into `RuntimeContext` through the `onBeforeRender` hook of Runtime plugins:
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+export default function MyComponent() {
+  const context = use(RuntimeContext);
+  const { message } = context;
+
+  return <div>{message}</div>;
+}
+```
+