@modern-js/app-tools 3.6.0 → 3.8.0

package/docs/apis/app/hooks/config/public.md

@@ -0,0 +1,26 @@
+# public/
+
+Any static assets can be placed in the `public/` directory, and the files will be deployed to the corresponding application domain by the server.
+
+## Description
+
+The file routing is based on the convention of the directory structure, where `public/` is the root directory corresponding to the root path of the Web application.
+
+For example, the `config/public/sdk/index.js` file will be deployed under `${domain}/sdk/index.js` after deployment.
+
+## Scenarios
+
+For example, authentication files required by third-party systems such as `robots.txt` and `auth.xml`.
+
+Or SDKs for other business parties (requiring unchanged routing), or HTML files without entry.
+
+:::info
+For static assets (such as SVG images) that need to be imported through import in the source code, it is recommended to manage them in the `src/assets` directory.
+
+:::
+
+## Code Compression
+
+If the file in the directory is a `.js` file, it will be automatically compressed during production environment construction.
+
+If the file ends with `.min.js`, it will not be compressed.

package/docs/apis/app/hooks/config/upload.md

@@ -0,0 +1,50 @@
+# upload/
+
+Any static assets can be placed in the `upload/` directory.
+
+## Description
+
+In the development environment, the static assets in this directory will be hosted under the `/upload` path. After building the application, the files in this directory will be copied to the dist directory.
+
+This file convention is mainly used for developers to use plugins to proactively upload static assets to the CDN.
+
+## Scenarios
+
+For example, SDKs for project use only, such as `google-analysis.js` (usually requires HTTP caching).
+
+Pictures, font files, common CSS, etc.
+
+## Code Compression
+
+If the file in the directory is a `.js` file, it will be automatically compressed during production environment construction.
+
+If the file ends with `.min.js`, it will not be compressed.
+
+## More Usage
+
+In React components, you can add this prefix through [Environment Variables](/guides/basic-features/env-vars.md#asset_prefix):
+
+```tsx
+export default () => {
+  return (
+    <img src={`${process.env.ASSET_PREFIX}/upload/banner.png`}></img>
+  );
+};
+```
+
+In addition, whether it is in [Custom HTML](/guides/basic-features/html.md) or any HTML file under [`config/public/`](/apis/app/hooks/config/public.md), you can directly use HTML tags to reference resources in the `config/upload/` directory:
+
+```html
+<script src="/upload/index.js"></script>
+```
+
+If you set the [`dev.assetPrefix`](/configure/app/dev/asset-prefix.md) or [`output.assetPrefix`](/configure/app/output/asset-prefix.md) prefix, you can also use template syntax to add the prefix directly:
+
+```html
+<script src="<%=assetPrefix %>/upload/index.js"></script>
+```
+
+:::info
+Modern.js does not support using files under `config/upload/` through URLs in `config/public/*.css` (such as background-image).
+
+:::

package/docs/apis/app/hooks/modern-config.md

@@ -0,0 +1,5 @@
+# modern.config.ts
+
+The Modern.js configuration file. Through this file, you can personalize the configuration of various aspects of the current project.
+
+To learn more about how to use the configuration, please refer to [Configuration Usage](/configure/app/usage.md).

package/docs/apis/app/hooks/server/server.md

@@ -0,0 +1,5 @@
+# modern.server.ts
+
+This file extends the Modern.js Server. In this file, you can configure [Middleware](/guides/advanced-features/web-server.md#middleware), [RenderMiddleware](/guides/advanced-features/web-server.md#rendermiddleware), or [Plugin](/guides/advanced-features/web-server.md#plugin) for the Server that starts with the Modern.js project.
+
+You can intercept and handle requests and responses, perform authentication and role checks, preprocess requests, and handle exceptions, etc. You can also insert specific business logic into the built-in processing logic (including route matching, resource addressing, header injection, page rendering, and static web hosting).

package/docs/apis/app/hooks/shared.md

@@ -0,0 +1,3 @@
+# shared/
+
+Shared source code directory. When there is common code in `api/`, `server/`, and `src/` in the project, you can put these codes in the `shared` directory instead of directly referencing them.

package/docs/apis/app/hooks/src/app.md

@@ -0,0 +1,30 @@
+# App.tsx
+
+The entry identifier when using [Self-controlled Routing](/guides/concept/entries.md#self-controlled-routing) in the application.
+
+`App.tsx` is not the actual application entry; Modern.js will automatically generate the real entry file, which is roughly as follows:
+
+```js
+// runtime-global-context
+import { setGlobalContext } from '@modern-js/runtime/context';
+import App from '@_modern_js_src/App';
+
+setGlobalContext({
+  App,
+});
+
+// index.tsx
+import './runtime-global-context';
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+render(<ModernRoot />, 'root');
+```
+
+When `createRoot` is executed, it will retrieve the registered Global App and generate the actual React component.
+
+:::note
+In scenarios with multiple entry points, each entry can have its own independent `App.tsx`. For more details, see [Entry Points](/guides/concept/entries.md).
+:::

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

@@ -0,0 +1,34 @@
+# entry.tsx
+
+Normally, the [`routes/`](/apis/app/hooks/src/routes.md) and [`App.tsx`](/apis/app/hooks/src/app.md) 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.md

@@ -0,0 +1,51 @@
+# 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.md

@@ -0,0 +1,5 @@
+# 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.md).

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

@@ -0,0 +1,86 @@
+# routes/
+
+The identifier for the entry point when the application uses [Conventional Routing](/guides/basic-features/routes/routes.md#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.md#useparams) to obtain the corresponding named parameter.
+
+When using the [loader](/guides/basic-features/data/data-fetch.md#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 a new API in React Router 7. For details, see [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+
+:::

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

@@ -0,0 +1,3 @@
+# \*.\[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/bff/use-hono-context.md

@@ -0,0 +1,27 @@
+# useHonoContext
+
+Used to obtain Hono 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.md

@@ -0,0 +1,19 @@
+# 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.md

@@ -0,0 +1,39 @@
+# 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`](/apis/app/runtime/core/create-root.md).
+- `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.md

@@ -0,0 +1,156 @@
+# 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>;
+}
+```