@modern-js/main-doc 2.0.0-beta.6 → 2.0.0-canary.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @modern-js/main-doc@2.0.0-beta.6 build /github/workspace/packages/toolkit/main-doc
+> @modern-js/main-doc@2.0.0-beta.6 build /Users/bytedance/Desktop/workspace/modern.js/packages/toolkit/main-doc
 > npx ts-node ./scripts/sync.ts
 

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/index_.md

@@ -1,6 +1,6 @@
 ---
 title: index.[tj]s
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 Entry identifier if App want use custom entry. In most case, [`App.[tj]sx`](/docs/apis/app/hooks/src/app) hook file can already meet our needs.

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/pages.md

@@ -1,6 +1,6 @@
 ---
 title: pages/
-sidebar_position: 2
+sidebar_position: 3
 ---
 
 Entry identifier if the application want uses file system-based routing.

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/routes.md

@@ -0,0 +1,86 @@
+---
+title: routes/
+sidebar_position: 2
+---
+
+The entry identifier when the application uses file system-based routing.
+
+When the project structure is of type `Routes directory entry`, the files in the `src/routes` directory are parsed to get the client-side routing configuration. See [Routing by convention](/docs/guides/basic-features/routes) for more details on usage.
+
+
+Any `layout.[tj]sx` and `page.[tj]sx` under `src/routes` will be used as a route to the application：
+```bash {3}
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+## basic example
+
+The directory names in the `routes` directory will be used as a mapping of the route url, where `layout.tsx` is used as the layout component and `page.tsx` as the content component, which is a leaf node of the whole route, for example the following directory structure：
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+The following two routes are produced:
+- `/`
+- `/user`
+
+## Dynamic Route
+
+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 directories:
+
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+The `routes/[id]/page.tsx` file will be converted to a `/:id` route. All `/xxx` will match that route, except for the `/blog` route, which can be matched exactly.
+
+In the component, you can get the corresponding parameters by [useParams](/docs/apis/app/runtime/router/#useparams).
+
+In the loader, params will be used as input to [loader](/docs/guides/basic-features/data-fetch#loader-function), and the corresponding parameters can be retrieved through the property `params`.
+
+## Layout component
+
+As in the example below, you can add a common layout component for all routing components by adding `layout.tsx`
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+You can represent child components in layout components by using `<Outlet>`:
+```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 6, see [Outlet] for details(https://reactrouter.com/en/main/components/outlet#outlet).
+:::

package/en/docusaurus-plugin-content-docs/current/components/global-proxy-config.md

@@ -0,0 +1,74 @@
+* Type: `string | Object`
+* Default: `null`
+
+When this option is configured, the development environment will start a global proxy, similar to [Fiddler](https://www.telerik.com/fiddler), [Charles](https://www.charlesproxy.com/) and other web proxy debugging tools, which can be used to view, modify HTTP/HTTPS requests, responses, and can also be used as a proxy server.
+
+
+:::tip 提示
+Using this option requires advance installation `@modern-js/plugin-proxy`。
+:::
+
+### Object
+
+Using this option requires that the value of `Object` be installed in advance, the `key` of the object corresponds to the matching `pattern`, and the `value` of the object corresponds to the matching `target`.
+
+Example:
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    proxy: {
+      'https://www.baidu.com': 'https://google.com.hk',
+      //可以通过 file 协议直接返回静态文件。
+      'https://example.com/api': 'file://./data.json',
+    }
+  }
+});
+```
+
+### String
+
+When the value is `string`, it can be used to specify a separate proxy file, for example:
+
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  dev: {
+    proxy: './proxy.js',
+  },
+});
+```
+
+```js title="proxy.js"
+module.exports = {
+  name: 'my-app',
+  rules: `
+    ^example.com:8080/api/***   http://localhost:3001/api/$
+  `,
+};
+```
+
+:::info
+Modern.js global proxy implementation is based on [whistle](https://wproxy.org/whistle/), for more matching patterns, please refer to: [Matching Patterns](https://wproxy.org/whistle/pattern.html)
+:::
+
+Execute `dev`, when the prompt is as follows, the proxy server starts successfully:
+
+```bash
+  App running at:
+
+  Local:    http://localhost:8080/
+  Network:  http://192.168.0.1:8080/
+
+ℹ  info      Starting the proxy server.....
+✔  success   Proxy Server start on localhost:8899
+```
+
+Access the `localhost:8899` to view the Network and configure proxy rules on the UI interface:
+
+![proxy UI](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
+
+:::caution Caution
+The https agent automatically installs the certificate to obtain root privileges. Please enter the password as prompted. ** The password is only used when the certificate is trusted and will not be leaked or used for other links **.
+:::
+

package/en/docusaurus-plugin-content-docs/current/components/global-proxy.md

@@ -0,0 +1,28 @@
+
+Modern.js provides out-of-the-box global proxy plugin `@modern-js/plugin-proxy`, which is based on [whistle](https://github.com/avwo/whistle) and can be used to view and modify HTTP/HTTPS requests and responses, and can also be used as an HTTP proxy server.
+
+### Set Proxy Rules
+
+After install the proxy plugin and filling in the rules, execute `pnpm run dev`, Modern.js will automatically enable the proxy server after the development server starts.
+
+Specific proxy rules can be set via the [`dev.proxy`](/docs/configure/app/dev/proxy) or the `config/proxy.js` file.
+
+### Use Proxy Dashboard
+
+After exec `pnpm run dev` command:
+
+```bash
+  App running at:
+
+  Local:    http://localhost:8080/
+  Network:  http://192.168.0.1:8080/
+
+ℹ  info      Starting the proxy server.....
+✔  success   Proxy Server start on localhost:8899
+```
+
+In the console you can see that the proxy server started successfully.
+
+Accessing the `http://localhost:8899` and, you can set the rules through the dashboard.
+
+![debug-proxy-ui](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/debug/debug-proxy-ui.png)

package/en/docusaurus-plugin-content-docs/current/configure/app/dev/proxy.md

@@ -4,77 +4,7 @@ sidebar_label: proxy
 
 # dev.proxy
 
-* Type: `string | Object`
-* Default: `null`
 
-When this option is configured, the development environment will start a global proxy, similar to [Fiddler](https://www.telerik.com/fiddler), [Charles](https://www.charlesproxy.com/) and other web proxy debugging tools, which can be used to view, modify HTTP/HTTPS requests, responses, and can also be used as a proxy server.
-
-
-:::tip 提示
-Using this option requires advance installation `@modern-js/plugin-proxy`。
-:::
-
-### Object
-
-Using this option requires that the value of `Object` be installed in advance, the `key` of the object corresponds to the matching `pattern`, and the `value` of the object corresponds to the matching `target`.
-
-Example:
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: {
-      'https://www.baidu.com': 'https://google.com.hk',
-      //可以通过 file 协议直接返回静态文件。
-      'https://example.com/api': 'file://./data.json',
-    }
-  }
-});
-```
-
-### String
-
-When the value is `string`, it can be used to specify a separate proxy file, for example:
-
-
-```typescript title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: './proxy.js',
-  },
-});
-```
-
-```js title="proxy.js"
-module.exports = {
-  name: 'my-app',
-  rules: `
-    ^example.com:8080/api/***   http://localhost:3001/api/$
-  `,
-};
-```
-
-:::info
-Modern.js global proxy implementation is based on [whistle](https://wproxy.org/whistle/), for more matching patterns, please refer to: [Matching Patterns](https://wproxy.org/whistle/pattern.html)
-:::
-
-Execute `dev`, when the prompt is as follows, the proxy server starts successfully:
-
-```bash
-  App running at:
-
-  Local:    http://localhost:8080/
-  Network:  http://192.168.0.1:8080/
-
-ℹ  info      Starting the proxy server.....
-✔  success   Proxy Server start on localhost:8899
-```
-
-Access the `localhost:8899` to view the Network and configure proxy rules on the UI interface:
-
-![proxy UI](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
-
-:::caution Caution
-The https agent automatically installs the certificate to obtain root privileges. Please enter the password as prompted. ** The password is only used when the certificate is trusted and will not be leaked or used for other links **.
-:::
+import GlobalProxyConfig from '@site-docs-en/components/global-proxy-config.md'
 
+<GlobalProxyConfig />

package/en/docusaurus-plugin-content-docs/current/configure/app/source/entries.md

@@ -62,7 +62,6 @@ When the value is `Object`, the following properties can be configured:
 
 * `entry`：`string`，entry file path。
 * `disableMount`：`boolean = false`，turn off Modern.js generate entry code。
-* `enableFileSystemRoutes`：`boolean = false`，[Use Conventional Routing](/docs/apis/app/hooks/src/pages)。
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -78,7 +77,6 @@ export default defineConfig({
       entry_spa: {
         // The entry path of a conventional route must be set to a directory
         entry: './src/about',
-        enableFileSystemRoutes: true,
       },
     },
   },

package/en/docusaurus-plugin-content-docs/current/configure/app/tools/tailwindcss.md

@@ -4,38 +4,32 @@ title: tools.tailwindcss
 sidebar_label: tailwindcss
 ---
 
-* Type: `Object | Function`
-* Default: See configuration details below.
+- Type: `Object | Function`
+- Default: See configuration details below.
 
 <details>
   <summary>TailwindCSS configuration details</summary>
 
 ```js
-  const tailwind = {
-    purge: {
-        enabled: options.env === 'production',
-        content: [
-          './config/html/**/*.html',
-          './config/html/**/*.ejs',
-          './config/html/**/*.hbs',
-          './src/**/*',
-        ],
-        layers: ['utilities'],
-    },
-    // https://tailwindcss.com/docs/upcoming-changes
-    future: {
-      removeDeprecatedGapUtilities: false,
-      purgeLayersByDefault: true,
-      defaultLineHeights: false,
-      standardFontWeights: false,
-    },
-    theme: source.designSystem // Use source.design System configuration as Tailwind CSS Theme configuration
-  }
+const tailwind = {
+  content: [
+    './config/html/**/*.html',
+    './config/html/**/*.ejs',
+    './config/html/**/*.hbs',
+    './src/**/*.js',
+    './src/**/*.jsx',
+    './src/**/*.ts',
+    './src/**/*.tsx',
+    './storybook/**/*',
+  ],
+  theme: source.designSystem, // Use source.design System configuration as Tailwind CSS Theme configuration
+};
 ```
 
 :::tip Tips
 More about: <a href="https://tailwindcss.com/docs/configuration" target="_blank">TailwindCSS configuration</a>。
 :::
+
 </details>
 
 When the value is of type `Object`, rhe configuration corresponding to [TailwindCSS](https://tailwindcss.com/docs/configuration) is merged with the default configuration through `Object.assign`.

package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "BFF",
+  "position": 1,
+  "link": {
+    "type": "doc",
+    "id": "guides/advanced-features/bff/index"
+  }
+}

package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/bff-proxy.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 5
+title: Use Proxy
+---
+
+By configuring the BFF proxy, API requests can be forwarded without manual coding
+
+:::caution
+Using a BFF proxy ensures that requests can enter the BFF handler. (eg the request path must contain a bff prefix)
+:::
+
+Writing the following BFF proxy configuration in the `modern.server-runtime.config.js` file will proxy requests sent to `http://localhost:8080/api/v1/topics` to `https://cnodejs.org/api/v1/topics`.
+
+```js title="modern.server-runtime.config.js"
+import { defineConfig } from '@modern-js/app-tools/server';
+export default defineConfig({
+  bff: {
+    proxy: {
+      '/api/v1/topics': 'https://cnodejs.org',
+    },
+  },
+};
+```
+
+:::note
+For more detail, see [bff.proxy](/docs/configure/app/bff/proxy)。For more proxy info, see [Proxy](/docs/guides/basic-features/proxy)。
+:::

package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/bff/frameworks.md

@@ -0,0 +1,148 @@
+---
+sidebar_position: 3
+title: Frameworks
+---
+
+## Function Writing
+
+Under the function writing, only the middleware writing method of various runtime frameworks is different, and other implementations are basically the same. Take Express as an example to introduce how to write a middleware by hand in the `api/_ app.ts` and add permission verification:
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+import { Request, Response, NextFunction } from 'express';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req: Request, res: Response, next: NextFunction) => {
+    if (req.url !== '/api/login') {
+      const sid = req?.cookies?.sid;
+      if (!sid) {
+        res.status(400);
+        res.json({ code: -1, message: 'need login' });
+      } else {
+        next();
+      }
+    } else {
+      next();
+    }
+  });
+});
+```
+
+然后添加一个普通的 BFF 函数 `/api/hello.ts`:
+
+```ts
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
+
+Finally, add the access code of the interface in the front-end `src/App.tsx`, and call it directly in an integrated way:
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchMyApi() {
+      const { message } = await hello();
+      setText(message);
+    }
+
+    fetchMyApi();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+Then exec `pnpm run dev` starts the project, and accessing `http://localhost:8080/` will find that the request for'/api/hello 'is blocked:
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+
+Finally, modify the front-end code `src/App.tsx` to call the login interface before accessing `/api/hello`:
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+import { post as login } from '@api/login';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchAfterLogin() {
+      const { code } = await login();
+      if (code === 0) {
+        const { message } = await hello();
+        setText(message);
+      }
+    }
+    fetchAfterLogin();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+Refresh the page and you can see that `/api/hello` was accessed successfully:
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
+
+The above code simulates the way to add middleware to the `/api/_app.ts` to achieve an easy login function. Also, other functions can be implemented in this hook file to extend BFF Server.
+
+## Framework Writing
+
+Under the framework writing, Modern.js does not collect middleware in the `api/_app.ts`, and the running process is controlled by the plugin itself.
+
+### Express
+
+The framework writing of Express supports defining the startup logic of API Server in `api/app.[tj]s`. performing the initialization work of the application, adding global middleware, declaring routes, and even extending the original framework.
+
+The route defined by the BFF function will be registered after the route defined by the `app.ts` file, so here you can also intercept the route defined by the BFF function, preprocess or respond in advance.
+
+```ts title="api/app.ts"
+import express from "express";
+
+const app = express();
+
+app.put("/user", function (req, res) {
+  res.send("Got a PUT request at /user");
+});
+
+app.use(async (req, res, next) => {
+  console.info(`access url: ${req.url}`);
+  next();
+});
+
+export default app;
+```
+
+### Koa
+
+The Koa framework is written in a similar way to Express. It supports defining the startup logic of API Server in `app.[tj]s`, performing the initialization work of the application, adding global middleware, declaring routes, extending the original framework, etc.
+
+The route defined by the BFF function will be registered after the route defined by the `app.ts` file, so here you can also intercept the route defined by the BFF function, preprocess or respond in advance.
+
+:::caution
+Use the framework writing, when there is no `app.ts`, Modern.js will add koa-body by default. When there is `app.ts`, if the developer wants to use the BFF function with Body, he needs to ensure that the koa-body middleware has been added.
+:::
+
+```ts title=api/app.ts
+import koa from "koa";
+
+const app = new Koa();
+
+app.put("/user", function (req, res) {
+  res.send("Got a PUT request at /user");
+});
+
+app.use(async (ctx, next) => {
+  console.info(`access url: ${ctx.url}`);
+  await next();
+});
+
+export default app;
+```