@modern-js/main-doc 2.1.0 → 2.2.0

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

@@ -1,150 +0,0 @@
----
-sidebar_position: 3
-title: Frameworks
----
-
-Modern.js's BFF supports different runtime frameworks, currently Modern.js's BFF supports two runtime frameworks[Express.js](https://expressjs.com/) 和 [Koa.js](https://koajs.com/).
-
-## 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;
-```

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

@@ -1,228 +0,0 @@
----
-sidebar_position: 1
-title: Basic Usage
----
-
-Applications developed with Modern.js can define API functions in the `api/` directory, which can be called by the front-end to send requests without writing front and back-end glue layer code, At the same time, it ensures the type safety of the front and back end
-
-## Enable BFF
-
-import EnableBFF from '@site-docs-en/components/enable-bff.md'
-
-<EnableBFF/>
-
-## BFF Function
-
-The functions that are allowed to be called through integration are called **BFF functions**. Here is the simplest BFF function to write, creating an `api/hello.ts` file:
-
-```ts title="api/hello.ts"
-export const get = async () => 'Hello Modern.js';
-```
-
-Then directly import the function in `src/App.tsx` and call:
-
-```tsx title=src/App.tsx
-import { useState, useEffect } from 'react';
-import { get as hello } from '@api/hello';
-
-export default () => {
-  const [text, setText] = useState('');
-
-  useEffect(() => {
-    hello().then(setText);
-  }, []);
-  return <div>{text}</div>;
-};
-```
-
-:::info
-Modern.js generator has already configured the `@api` alias in tsconfig.json, so you can import functions directly by aliases.
-:::
-
-The functions import in `src/App.tsx` will be automatically converted into interface calls, so there is no need to call the interface through fetch.
-
-Execute `pnpm run dev`, then open `http://localhost:8080/` to see that the page has displayed the content returned by the BFF function. In Network, you can see that the page sent a request to `http://localhost:8080/api/hello`.
-
-![Network](https://p6-piu.byteimg.com/tos-cn-i-8jisjyls3a/fd41750f8d414179a9b4ecb519919b36~tplv-8jisjyls3a-3:0:0:q75.png)
-
-## API Routes
-
-In Modern.js, the BFF function routing system is implemented based on the file system, and it is also a conventional routing system.
-
-In **Function Writing**, All files under `api/` will map to an interface. In **Framework Writing**, All files under `api/lambda` will map to an interface
-
-:::note
-Function Writing & Framework Writing will introduce soon.
-:::
-
-All routes generated by BFF functions have a prefix, and the default value is `/api`. The prefix can be set through [bff.prefix] (/docs/configure/app/bff/prefix).
-
-Several routing conventions are described as follow.
-
-### Default Route
-
-Files named `index.[jt]s` are mapped to the previous directory.
-
-- `api/index.ts` -> `{prefix}/`
-- `api/user/index.ts` -> `{prefix}/user`
-
-### Multi-layer Route
-
-Supports parsing nested files, if you create a nested folder structure, the files will still automatically parse routes in the same way.
-
-- `api/hello.ts` -> `{prefix}/hello`
-- `api/user/list.ts` -> `{prefix}/user/list`
-
-### Dynamic Route
-
-Create folders or files named with `[xxx]` to support dynamic named routing parameters.
-
-- `api/user/[username]/info.ts` -> `{prefix}/user/:username/info`
-- `api/user/username/[action].ts` -> `{prefix}/user/username/:action`
-
-### Allow List
-
-By default, all files in the'api/'directory will be parsed as BFF function files, but the following files will not be parsed:
-
-- file name start with `_`, for example `_utils.ts`.
-- files in directory which name start with `_`, for example `_utils/index.ts`、`_utils/cp.ts`.
-- test files, for example `foo.test.ts`.
-- type files, for example `hello.d.ts`.
-- files in `node_module`.
-
-## RESTful API
-
-Modern.js BFF functions need to be defined according to the RESTful API standard, follow the HTTP Method specification, and do not allow free parameter definition.
-
-:::info
-Assuming that the function allows free definition of parameters, the resulting route must be called by the **private protocol** (the reason is that the request parameters cannot be distinguished from the request body), and cannot implement any RESTful API.
-
-If the service is only used for the application itself, there is no problem. but its **non-standard interface definition** cannot be integrated into the larger system. In the case of multiple systems working together (such as BFF low-code construction), other systems also need to follow the **private protocol**.
-:::
-
-### Function Named Export
-
-Modern.js the export name of the BFF function determines the Method of the corresponding interface of the function, such as `get`, `post` and so on.
-
-For example, following the example, a `GET` interface can be exported.
-
-```ts
-export const get = async () => {
-  return {
-    name: 'Modern.js',
-    desc: '现代 web 工程方案',
-  };
-};
-```
-
-Following the example below, a `POST` interface can be exported.
-
-```ts
-export const post = async () => {
-  return {
-    name: 'Modern.js',
-    desc: '现代 web 工程方案',
-  };
-};
-```
-
-- Modern.js supports 9 definitions for HTTP Method: `GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`, can be exported using these methods as functions。
-
-- The name is size insensitive，if `GET`，can write `get`、`Get`、`GEt`、`GET`，can be accurately identified. But default export as `export default xxx` will be map to `Get`。
-
-- Multiple functions of different Methods can be defined in one file, but if multiple functions of the same Method are defined, only the first will take effect.
-
-:::info
-It should be noted that the defined functions should all be asynchronous, which is related to the type when the function is called, which will be mentioned later.
-:::
-
-### Function Parameter Rule
-
-As mentioned above, in order to meet the design criteria of RESTful APIs, the BFF function in Modern.js needs to follow certain imported parameter rules.
-
-The function parameters are divided into two parts, the dynamic part in the request path and the request option `RequestOption`.
-
-#### Dynamic Path
-
-Dynamic routing will be used as imported parameters in the first part of the function, and each imported parameter corresponds to a dynamic route. For example, in the following example, uid will be passed into the function as the first two parameters:
-
-```ts title="api/[level]/[id].ts"
-export default async (level: number, id: number) => {
-  const userData = await queryUser(level, uid);
-  return userData;
-};
-```
-
-Pass dynamic parameters directly when calling:
-
-```ts title="App.tsx"
-import { useState, useEffect } from 'react';
-import { get as getUser } from '@api/[level]/[id]';
-
-export default () => {
-  const [name, setName] = useState('');
-
-  useEffect(() => {
-    getUser(6, 001).then(userData => setName(userData.name));
-  }, []);
-
-  return <div>{name}</div>;
-};
-```
-
-#### RequestOption
-
-The parameter after Dynamic Path is the object `RequestOption` containing querystring and request body, which is used to define the types of `data` and `query`.
-
-In normal functions without dynamic routing, the incoming `data` and `query` can be obtained from the first imported parameter, for example:
-
-```ts title="api/hello.ts"
-import type { RequestOption } from '@modern-js/runtime/server';
-
-export async function post({
-  query,
-  data,
-}: RequestOption<Record<string, string>, Record<string, string>>) {
-  // do somethings
-}
-```
-
-When a function file uses dynamic routing rules, dynamic routing before the `RequestOption` parameter.
-
-```ts title="api/[sku]/[id]/item.ts"
-export async function post(
-  sku: string,
-  id: string,
-  {
-    data,
-    query,
-  }: RequestOption<Record<string, string>, Record<string, string>>,
-) {
-  // do somethings
-}
-```
-
-Also pass in the parameters according to the function definition:
-
-```ts title="App.tsx"
-import { post } from '@api/[sku]/[id]/item';
-
-export default () => {
-  const addSku = () => {
-    post('0001' /* sku */, '1234' /* id */, {
-      query: {
-        /* ... */
-      },
-      data: {
-        /* ... */
-      },
-    });
-  };
-
-  return <div onClick={addSku}>添加 SKU</div>;
-};
-```
-
-As mentioned earlier, the defined functions should be asynchronous because they are automatically converted to HTTP interface calls when called by the front end.
-
-so in order to keep the type definition consistent with the actual calling, it is necessary to set the BFF function to asynchronous when defining it.

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

@@ -1,20 +0,0 @@
----
-title: BFF
----
-
-In the development of the concept of **front back separation**, the front-end part can do more and more things, and the front-end needs some UI-oriented data interfaces, so the industry introduced the concept of BFF (Backends for Frontends).
-
-The main problems it to solve include:
-
-- Aggregation, mapping, clipping, and proxying of lower-level APIs according to their own business needs.
-- Cache data for some specific scenarios to improve performance and thus improve user experience.
-- Quickly development of new products based on existing interfaces.
-- Interface with third-party systems, such as login authentication.
-
-Modern.js officially supported the BFF and provided the **Integrated BFF** to further strengthen the BFF's capabilities, mainly including the following capabilities:
-
-- Quick development and debugging go live, running, building, and deploying BFF code in the same project.
-- Minimal pure function call, directly import BFF function on the front end, and can be automatically converted into HTTP request when called.
-- No private protocol, follow RESTful API specification, all BFF interfaces are standardized.
-- Full TypeScript support.
-- Meet user preferences and support multi-frame extension writing.

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

@@ -1,42 +0,0 @@
----
-sidebar_position: 2
-title: Writing Type
----
-
-Runtime framework support is also an important part of **BFF**. Modern.js supports extending BFF's runtime framework through plugins, and provides a series of built-in plugins, developers can directly use the conventions and ecology of the framework.
-
-The plugin is compatible with most of the specifications of these frameworks, and each framework needs to provide two types of ways to extend the writing of BFF functions, namely **Function Writing** and **Framework Writing**.
-
-:::note
-Whether the current `api/` directory structure is written as a framework is determined by the corresponding plugin, Modern.js don't care.
-:::
-
-## Function Writing
-
-When the plugin considers that it is currently written as a function, it must support writing middleware in the `api/_ app.ts` to extend the BFF function.
-
-Modern.js collects the middleware in the `api/_app.ts` and passes it to the plugin, which injects the middleware into the runtime, for example:
-
-```ts
-import { hook } from '@modern-js/runtime/server';
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware(myMiddleware);
-});
-```
-
-:::note
-The writing of middleware for different plugins is not the same, see [Runtime Framework](/docs/guides/advanced-features/bff/frameworks) for details.
-:::
-
-## Framework Writing
-
-Framework writing is a way of using frame structure to extend BFF functions. Compared with function writing, although frame writing can use more frame structure and make the entire BFF Server clearer in complex scenarios, it is also more complex and requires more attention to the content at the framework level.
-
-In the framework writing method, all BFF functions need to be written in the `api/lambda/` directory, and the hook file `_app.[tj]s` cannot be used.
-
-In most cases, the function writing method can cover the customization requirements of most BFF functions. Only when your project server level logic is more complex, the code needs to be layered, or you need to use more elements of the framework, you need to use the framework writing method.
-
-:::note
-The directory structure of different plugin frameworks is not the same, see [Runtime Frameworks](/docs/guides/advanced-features/bff/frameworks) for details.
-:::

package/en/docusaurus-plugin-content-docs/current/guides/advanced-features/code-split.md

@@ -1,76 +0,0 @@
----
-title: Code Split
-sidebar_position: 6
----
-
-Code Split is a common way to optimizing front-end resource loading. This doc will introduce three methods supported by Modern.js:
-
-:::info
-When you use Modern.js [Conventional routing](/docs/guides/basic-features/routes#conventional-routing), by default it will do code splitting based on routing components, wrapping `Suspense` components, no need to do code splitting by yourself.
-:::
-
-- `import`
-- `React.lazy`
-- `loadable`
-
-## import
-
-use dynamic `import()`，`import` The JS modules pass to this API will be packaged into a separate JS file as a new packaging entry, for example:
-
-```ts
-import('./math').then(math => {
-  console.log(math.add(16, 26));
-});
-```
-
-The JS modules corresponding to the './math' path will be packaged in a separate JS file.
-
-## React.lazy
-
-The officially way provides by React to split component code.
-
-:::caution
-SSR is not supported in React 17 and below, and it is recommended that SSR applications for React 17 use loadable.
-:::
-
-```ts
-import React, { Suspense } from 'react';
-
-const OtherComponent = React.lazy(() => import('./OtherComponent'));
-const AnotherComponent = React.lazy(() => import('./AnotherComponent'));
-
-function MyComponent() {
-  return (
-    <div>
-      <Suspense fallback={<div>Loading...</div>}>
-        <section>
-          <OtherComponent />
-          <AnotherComponent />
-        </section>
-      </Suspense>
-    </div>
-  );
-}
-```
-
-For detail, see [React lazy](https://reactjs.org/docs/code-splitting.html#reactlazy)。
-
-## loadable
-
-use `loadable` API，for example：
-
-```ts
-import loadable from '@modern-js/runtime/loadable';
-
-const OtherComponent = loadable(() => import('./OtherComponent'));
-
-function MyComponent() {
-  return <OtherComponent />;
-}
-```
-
-For detail, see [loadable API](/docs/apis/app/runtime/utility/loadable)。
-
-:::info
-SSR is supported out of the box by `loadable`.
-:::

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

@@ -1,75 +0,0 @@
----
-title: Compatibility
-sidebar_position: 5
----
-
-## Browserslist
-
-Modern.js supports the `browserslist` field in the `package.json` file, or a `.browserslistrc` file to specify the target browser range covered by the project.
-
-This value is used by ['@babel/preset-env'] (https://babeljs.io/docs/en/babel-preset-env) and ['autoprefixer'] (https://github.com/postcss/autoprefixer) to determine the JavaScript syntax features to be converted and the CSS browser prefix to be added.
-
-The default value in Modern.js as follow:
-
-```js
-['> 0.01%', 'not dead', 'not op_mini all'];
-```
-
-You can learn how to customize the browserlist [here](https://github.com/browserslist/browserslist).
-
-See Modern.js Builder docs to learn more [Browserlist](https://modernjs.dev/builder/zh/guide/advanced/browserslist.html) info.
-
-:::note
-Modern.js also supports configuring [output.override Browserlist](/docs/configure/app/output/override-browserslist) to override the default browserlist value.
-:::
-
-## Polyfill
-
-### Polyfill At Compile
-
-Modern.js inject the Polyfill code via [core-js] (https://github.com/zloirock/core-js) at compile time by default.
-
-By default, the required Polyfill code will be introduced according to the settings of the Browserslist, so there is no need to worry about the Polyfill problem of the project source code and third-party dependencies, but because it contains some Polyfill code that is not used, the final bundle size may be increased.
-
-:::info
-For case where Polyfill is not required for third-party dependencies, you can set ['output.polyfill'](/docs/configure/app/output/polyfill) to `usage`, so that Babel compiles only Polyfill code based on the syntax used in the code.
-:::
-
-### Polyfill At Runtime
-
-Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information, which has the following advantages over Babel:
-
-- It will not be inserted into the code, reducing the code .
-- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster.
-
-exec `pnpm run new` to enable this features：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「基于 UA 的 Polyfill」功能
-```
-
-After executing the command, register the Polyfill plugin in `modern.config.ts`:
-
-```ts title="modern.config.ts"
-import polyfillPlugin from '@modern-js/plugin-polyfill';
-
-// https://modernjs.dev/docs/apis/app/config
-export default defineConfig({
-  plugins: [..., polyfillPlugin()],
-});
-```
-
-After configuring `output.polyfill` as `ua` and executing `pnpm run build & & pnpm run serve` to start the server, visiting the page can see that the HTML product contains the following script:
-
-```js
-<script src="/__polyfill__" crossorigin></script>
-```
-
-Visit the page `http://localhost:8080/__polyfill__` on Chrome 51 to see:
-
-![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
-
-:::caution
-This feature only works when using Modern.js built-in Web Server.
-:::