@modern-js/main-doc 2.35.1 → 2.36.0

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

@@ -54,7 +54,7 @@ The `routes/[id]/page.tsx` file will be converted to the `/:id` route. Except fo
 
 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-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`.
+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
 

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

@@ -6,7 +6,7 @@ $ pnpm run dev
 > modern dev
 
 info    Starting dev server...
-ready   Client compiled in 50ms
+ready   Client compiled in 50 ms
 
   > Local:    http://localhost:8080/
   > Network:  http://192.168.0.1:8080/

package/docs/en/components/turtorials-example-list.mdx

@@ -0,0 +1,2 @@
+- [Route Authorization](/tutorials/examples/csr-auth.html)
+- ...

package/docs/en/configure/app/source/entries.mdx

@@ -39,8 +39,8 @@ import { defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   source: {
     entries: {
-      // Specify a new entry named entry_customize
-      entry_customize: './src/home/test/index.ts',
+      // Specify a new entry named 'my-entry'
+      'my-entry': './src/home/test/index.ts',
     },
     disableDefaultEntries: true,
   },
@@ -90,9 +90,10 @@ import { defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   source: {
     entries: {
-      entry_customize: {
+      'my-entry': {
         // entry file path
-        entry: './src/home/test/App.tsx',
+        entry: './src/my-page/index.tsx',
+        disableMount: true,
       },
     },
     // Disable default entry scanning
@@ -111,8 +112,8 @@ If you want to disable the logic of Modern.js automatically generating entry fil
 export default defineConfig({
   source: {
     entries: {
-      entry_customize: {
-        entry: './src/home/test/index.tsx',
+      'my-entry': {
+        entry: './src/my-page/index.tsx',
         disableMount: true,
       },
     },

package/docs/en/guides/advanced-features/bff/sdk.mdx

@@ -0,0 +1,119 @@
+---
+sidebar_position: 4
+title: Custom request SDK
+---
+# Custom request SDK
+
+Modernjs's BFF is isomorphic in CSR and SSR.In the browser side rely on the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch)，On the server relies on the [node-fetch](https://www.npmjs.com/package/node-fetch).However, in many business scenarios we need to do some additional processing of the request or response, for example:
+
+- Write auth information in the request header
+- Uniform processing of response data or errors
+- The browser's native fetch function is not available for a particular platform, and other methods of sending requests are required
+
+For the above scenario, Modern.js provides the `configure` function，the customization capabilities range from low to high and can be used to configure ssr pass-through request headers, interceptors, and request SDKs..
+
+:::caution
+The `configure` function call needs to be called before all BFF requests are sent, to ensure that the default request configuration is overridden.
+
+:::
+
+
+```ts title="App.tsx"
+import { configure } from '@modern-js/runtime/bff';
+
+configure({
+  request: customRequest
+})
+```
+
+## Configure ssr pass-through request headers
+
+In scenarios where both Modern.js SSR and BFF are used, it is often necessary to pass some request headers on SSR page requests to the BFF service.
+
+For example, the project has a page address `https://website.com`, which is an SSR page, and the API interface `https://website.com/api/info` will be called in the component, which requires the user's cookie information for authentication. When the page requests this API interface, it needs to pass the `cookie` requested by the SSR page to BFF.
+
+Currently the following request headers are automatically passed through in Modern.js:
+
+- cookie
+- x-tt-logid
+- user-agent
+- x-tt-stress
+
+The request header can be configured via `configure`. For example, in the following example, Modern.js will automatically pass the cookie information of the SSR page request to the BFF service:
+
+```tsx title="App.tsx"
+import { configure } from '@modern-js/runtime/bff';
+
+configure({
+  allowedHeaders: ['x-uid']
+})
+```
+
+## Configuring Interceptors
+
+In certain business scenarios, there is a requirement for unified processing of requests and responses, and interceptors can be configured to fulfill these requirements in such scenarios.
+
+```tsx title="App.tsx"
+configure({
+  // The request here is the default request sdk for bff, and the interceptor function needs to return a new request.
+  // The return value of the new request must be the result of the parse body
+  interceptor(request){
+    return async(url, params) => {
+      const res = await request(url, params);
+      return res.json();
+    };
+  };
+});
+```
+
+## Configure custom request SDK
+
+If the requirements cannot be met by configuring interceptors alone  and need to further customize the request SDK, you can configure the custom request SDK by using the `configure` function:
+
+:::caution
+Send a request to the BFF service when the server side renders, Modern.js will find the BFF service intranet IP via **service discovery** and send requests via IP to improve performance. This optimization is **lost** if a custom request SDK is used.
+
+:::
+
+```tsx title="App.tsx"
+import nodeFetch from 'node-fetch';
+
+const customFetch = (input: RequestInfo | URL, init: RequestInit) => {
+  const curFetch = process.env.MODERN_TARGET !== 'node' ? fetch : nodeFetch as unknown as typeof fetch;
+  return curFetch(input, init).then(async res => {
+    const data = await res.json();
+    data.hello = 'hello custom sdk';
+    return data;
+  });
+};
+
+configure({
+  request: customFetch,
+});
+```
+
+The configuration custom request SDK has the following conventions:
+
+- The `configure` function allows you to configure a `request` function whose input is the same as the Fetch or node-fetch in the browser, and all BFF functions will send requests through this function
+- The return value of the `request` function must be the actual data returned by the interface, not a Promise, otherwise the BFF function will not return data properly.
+- In the case of SSR projects, `request` must support both browser-side and server-side sending of requests.
+
+Example of custom request SDK using axios:
+
+```tsx title="App.tsx"
+import { configure } from '@modern-js/runtime/bff';
+import type { Method, AxiosRequestHeaders as Headers } from 'axios';
+
+configure({
+  async request(...config: Parameters<typeof fetch>) {
+    const [url, params] = config;
+    const res = await axios({
+      url: url as string,  // Here, because of some incompatibility between fetch and axios types, you need to use `as`
+      method: params?.method as Method,
+      data: params?.body,
+      headers: params?.headers as Headers,
+    });
+    return res.data;
+  },
+});
+```

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -26,7 +26,7 @@ After the project is created, you can experience the project by running `pnpm ru
 When using Rspack as the bundler, the following Features are temporarily unavailable as some of the capabilities are still under development and we will provide support in the future.
 
 - Storybook Devtool
-- The usage of [useLoader](/guides/basic-features/data-fetch.html) in Client Side Rendering
+- The usage of [useLoader](/guides/basic-features/data/data-fetch.html) in Client Side Rendering
 
 :::
 

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

@@ -22,8 +22,8 @@ export default defineConfig({
 
 Modern.js provides a Data Loader that simplifies data fetching for developers working with SSR and CSR. Each routing module, such as `layout.tsx` and `page.tsx`, can define its own Data Loader:
 
-```ts title="src/routes/page.loader.ts"
-export default () => {
+```ts title="src/routes/page.data.ts"
+export const loader = () => {
   return {
     message: 'Hello World',
   };
@@ -49,7 +49,7 @@ Developers should still be mindful of data fallback, including `null` values or
 
 1. When requesting a page through client-side routing, Modern.js sends an HTTP request. The server receives the request and executes the corresponding Data Loader function for the page, then returns the execution result as a response to the browser.
 
-2. When using Data Loader, data is fetched before rendering. Modern.js also supports obtaining data during component rendering. For more related content, please refer to [Data Fetch](/guides/basic-features/data-fetch).
+2. When using Data Loader, data is fetched before rendering. Modern.js also supports obtaining data during component rendering. For more related content, please refer to [Data Fetch](/guides/basic-features/data/data-fetch).
 
 :::
 
@@ -158,10 +158,10 @@ Using SPR in Modern.js is very simple. Just add the PreRender component to your
 
 Here is a simulated component that uses the useLoaderData API. The request in the Data Loader takes 2 seconds to consume.
 
-```tsx title="page.loader.ts"
+```tsx title="page.data.ts"
 import { useLoaderData } from '@modern-js/runtime/router';
 
-export default async () => {
+export const loader = async () => {
   await new Promise((resolve, reject) => {
     setTimeout(() => {
       resolve(null);
@@ -307,9 +307,9 @@ export const loader = () => {
 
 The two methods mentioned above will both bring some mental burden to developers. In real business scenarios, we found that most of the mixed Node/Web code appears in data requests.
 
-Therefore, Modern.js has designed a [Data Fetch](/guides/basic-features/data-fetch) to separate CSR and SSR code based on [Nested Routing](/guides/basic-features/routes).
+Therefore, Modern.js has designed a [Data Fetch](/guides/basic-features/data/data-fetch) to separate CSR and SSR code based on [Nested Routing](/guides/basic-features/routes).
 
-We can separate **data requests from component code** by using independent files. Write the component logic in `routes/page.tsx` and write the data request logic in `routes/page.loader.ts`.
+We can separate **data requests from component code** by using independent files. Write the component logic in `routes/page.tsx` and write the data request logic in `routes/page.data.ts`.
 
 ```ts title="routes/page.tsx"
 export default Page = () => {
@@ -317,9 +317,9 @@ export default Page = () => {
 }
 ```
 
-```ts title="routes/page.loader.tsx"
+```ts title="routes/page.data.tsx"
 import fse from 'fs-extra';
-export default () => {
+export const loader = () => {
   const file = fse.readFileSync('./myfile');
   return {
     ...
@@ -329,7 +329,7 @@ export default () => {
 
 ## Remote Request
 
-When initiating interface requests in SSR, developers sometimes encapsulate isomorphic request tools themselves. For some interfaces that require passing user cookies, developers can use the ['useRuntimeContext'](/guides/basic-features/data-fetch#route-loader) API to get the request header for implementation.
+When initiating interface requests in SSR, developers sometimes encapsulate isomorphic request tools themselves. For some interfaces that require passing user cookies, developers can use the ['useRuntimeContext'](/guides/basic-features/data/data-fetch#route-loader) API to get the request header for implementation.
 
 It should be noted that the obtained request header is for HTML requests, which may not be suitable for API requests. Therefore, ** don't passed through all request headers **.
 
@@ -361,7 +361,7 @@ The streaming SSR of Modern.js is implemented based on React Router, and the mai
 
 ### Return async data
 
-```ts title="page.loader.ts"
+```ts title="page.data.ts"
 import { defer, type LoaderFunctionArgs } from '@modern-js/runtime/router';
 
 interface User {
@@ -373,7 +373,7 @@ export interface Data {
   data: User;
 }
 
-export default ({ params }: LoaderFunctionArgs) => {
+export const loader = ({ params }: LoaderFunctionArgs) => {
   const userId = params.id;
 
   const user = new Promise<User>(resolve => {
@@ -393,7 +393,7 @@ export default ({ params }: LoaderFunctionArgs) => {
 
 `defer` can receive both asynchronous and synchronous data at the same time. For example:
 
-```ts title="page.loader.ts"
+```ts title="page.data.ts"
 // skip some codes
 
 export default ({ params }: LoaderFunctionArgs) => {
@@ -430,7 +430,7 @@ With the `<Await>` component, you can retrieve the data asynchronously returned
 ```tsx title="page.tsx"
 import { Await, useLoaderData } from '@modern-js/runtime/router';
 import { Suspense } from 'react';
-import type { Data } from './page.loader';
+import type { Data } from './page.data';
 
 const Page = () => {
   const data = useLoaderData() as Data;
@@ -461,7 +461,7 @@ export default Page;
 :::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.loader'`;
+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:
@@ -504,10 +504,10 @@ export default Page;
 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.loader.ts"
+```ts title="page.data.ts"
 import { defer } from '@modern-js/runtime/router';
 
-export default () => {
+export const loader = () => {
   const data = new Promise((resolve, reject) => {
     setTimeout(() => {
       reject(new Error('error occurs'));

package/docs/en/guides/basic-features/data/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Data solution",
+  "position": 3
+}

package/docs/en/guides/basic-features/{data-fetch.mdx → data/data-fetch.mdx}

@@ -14,13 +14,19 @@ It should be noted that these APIs do not help applications initiate requests, b
 Modern.js recommends using [conventional routing](/guides/basic-features/routes) for routing management. Through Modern.js's [conventional (nested) routing](/guides/basic-features/routes#conventional-routing), each routing component (`layout.ts` or `page.ts`) can have a same-named `loader` file. The `loader` file needs to export a function that will be executed before the component is rendered to provide data for the routing component.
 
 :::info
-Modern.js v1 supports fetching data via [useLoader](</guides/basic-features/data-fetch.html#useloader-(old-version)>), which is no longer the recommended usage. We do not recommend mixing the two except during the migration process.
+Modern.js v1 supports fetching data via [useLoader](</guides/basic-features/data/data-fetch.html#useloader-(old-version)>), which is no longer the recommended usage. We do not recommend mixing the two except during the migration process.
+
+:::
+
+:::warning
+- In the previous version, Modern.js Data Loader was defined in the `loader` file. In later versions, we recommend defining it in the `data` file, while we will maintain compatibility with the `loader` file.
+- In the `data` file, the corresponding `loader` needs to be exported with a name。
 
 :::
 
 ### Basic Example
 
-Routing components such as `layout.ts` or `page.ts` can define a same-named `loader` file. The function exported by the `loader` file provides the data required by the component, and then the data is obtained in the routing component through the `useLoaderData` function, as shown in the following example:
+Routing components such as `layout.ts` or `page.ts` can define a same-named `loader` file. The function exported by the `data` file provides the data required by the component, and then the data is obtained in the routing component through the `useLoaderData` function, as shown in the following example:
 
 ```bash
 .
@@ -28,16 +34,16 @@ Routing components such as `layout.ts` or `page.ts` can define a same-named `loa
     ├── layout.tsx
     └── user
         ├── layout.tsx
-        ├── layout.loader.ts
+        ├── layout.data.ts
         ├── page.tsx
-        └── page.loader.ts
+        └── page.data.ts
 ```
 
 Define the following code in the file:
 
 ```ts title="routes/user/page.tsx"
 import { useLoaderData } from '@modern-js/runtime/router';
-import type { ProfileData } from './page.loader.ts';
+import type { ProfileData } from './page.data.ts';
 
 export default function UserPage() {
   const profileData = useLoaderData() as ProfileData;
@@ -45,19 +51,19 @@ export default function UserPage() {
 }
 ```
 
-```ts title="routes/user/page.loader.ts"
+```ts title="routes/user/page.data.ts"
 export type ProfileData = {
   /*  some types */
 };
 
-export default async (): Promise<ProfileData> => {
+export const loader = async (): Promise<ProfileData> => {
   const res = await fetch('https://api/user/profile');
   return await res.json();
 };
 ```
 
 :::caution
-Here, routing components and `loader` files share a type, so the `import type` syntax should be used.
+Here, routing components and `data` files share a type, so the `import type` syntax should be used.
 
 :::
 
@@ -81,7 +87,7 @@ The `loader` function has two input parameters:
 When the route file is accessed through `[]`, it is used as [dynamic routing](/guides/basic-features/routes#dynamic-routing), and the dynamic routing fragment is passed as a parameter to the `loader` function:
 
 ```tsx
-// routes/user/[id]/page.loader.tsx
+// routes/user/[id]/page.data.tsx
 import { LoaderFunctionArgs } from '@modern-js/runtime/router';
 
 export default async ({ params }: LoaderFunctionArgs) => {
@@ -100,10 +106,10 @@ When accessing `/user/123`, the parameter of the `loader` function is `{ params:
 A common usage scenario is to get query parameters through `request`:
 
 ```tsx
-// routes/user/[id]/page.loader.ts
+// routes/user/[id]/page.data.ts
 import { LoaderFunctionArgs } from '@modern-js/runtime/router';
 
-export default async ({ request }: LoaderFunctionArgs) => {
+export const loader = async ({ request }: LoaderFunctionArgs) => {
   const url = new URL(request.url);
   const userId = url.searchParams.get('id');
   return queryUser(userId);
@@ -152,8 +158,8 @@ function loader() {
 In the `loader` function, errors can be handled by throwing an `error` or a `response`. When an error is thrown in the `loader` function, Modern.js will stop executing the code in the current `loader` and switch the front-end UI to the defined [`ErrorBoundary`](/guides/basic-features/routes#error-handling) component:
 
 ```tsx
-// routes/user/profile/page.loader.tsx
-export default async function loader() {
+// routes/user/profile/page.data.tsx
+export const loader = async function loader() {
   const res = await fetch('https://api/user/profile');
   if (!res.ok) {
     throw res;
@@ -185,7 +191,7 @@ In many cases, child components need to access data in the parent component `loa
 import { useRouteLoaderData } from '@modern-js/runtime/router';
 
 export default function UserLayout() {
-  // Get the data returned by the loader in routes/user/layout.loader.ts
+  // Get the data returned by the loader in routes/user/layout.data.ts
   const data = useRouteLoaderData('user/layout');
   return (
     <div>
@@ -219,12 +225,12 @@ If you want to get the data returned by the `loader` in `entry1/routes/layout.ts
 This feature is currently experimental and the API may change in the future.
 :::
 
-Create `user/layout.loader.ts` and add the following code:
+Create `user/layout.data.ts` and add the following code:
 
-```ts title="routes/user/layout.loader.ts"
+```ts title="routes/user/layout.data.ts"
 import { defer } from '@modern-js/runtime/router';
 
-const loader = () =>
+export const loader = () =>
   defer({
     userInfo: new Promise(resolve => {
       setTimeout(() => {
@@ -236,7 +242,6 @@ const loader = () =>
     }),
   });
 
-export default loader;
 ```
 
 Add the following code in `user/layout.tsx`:
@@ -286,24 +291,27 @@ Currently, there is no such restriction under CSR, but we strongly recommend tha
 
 ```ts
 // This won't work!
-export default () => {
-  return {
-    user: {},
-    method: () => {},
-  };
+export const loader = async () => {
+  const res = fetch('https://api/user/profile');
+  return res.json();
 };
+
+import { loader } from './page.data.ts';
+export default function RouteComp() {
+  const data = loader();
+}
 ```
 
 2. Modern.js will call the `loader` function for you, so you should not call the `loader` function yourself:
 
 ```tsx
 // This won't work!
-export default async () => {
+export const loader = async () => {
   const res = fetch('https://api/user/profile');
   return res.json();
 };
 
-import loader from './page.loader.ts';
+import { loader } from './page.data.ts';
 export default function RouteComp() {
   const data = loader();
 }
@@ -315,7 +323,7 @@ export default function RouteComp() {
 // Not allowed
 // routes/layout.tsx
 import { useLoaderData } from '@modern-js/runtime/router';
-import { ProfileData } from './page.loader.ts'; // should use "import type" instead
+import { ProfileData } from './page.data.ts'; // should use "import type" instead
 
 export const fetch = wrapFetch(fetch);
 
@@ -324,7 +332,7 @@ export default function UserPage() {
   return <div>{profileData}</div>;
 }
 
-// routes/layout.loader.ts
+// routes/layout.data.ts
 import { fetch } from './layout.tsx'; // should not be imported from the routing component
 export type ProfileData = {
   /*  some types */