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

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/testing/render.md

@@ -0,0 +1,72 @@
+---
+title: render
+---
+
+Used to render the component in the test case.
+
+## Usage
+
+```ts
+import { render } from '@modern-js/runtime/testing';
+```
+
+## Function Signature
+
+```ts
+type Options = {
+  container: DOMElement;
+  baseElement: DOMElement;
+  hydrate: boolean;
+  warpper: React.ComponentType<{children: ReactNode}>;
+  queries: any;
+};
+
+type RenderResult = {
+  {...queries}: any;
+  container: DOMElement;
+  baseElement: DOMElement;
+  debug: function;
+  rerender: function;
+  unmount: function;
+  asFragment: function;
+}
+
+function render(ui: React.ReactElement<any>, options: Options): RenderResult;
+```
+
+### Input
+
+- `ui`: the React component that needs to be rendered.
+- `options`: render options.
+  - `container`: the dom which component mounted. by default create a `div` element，and auto append to `document.body`. the default value is `document.body.append(document.createElement('div'))`.
+  - `baseElement`: Used to specify the `basename` used in `queries`. If `container` is specified, the default value is the value of `container`, otherwise it is `document.body`.
+  - `hydrate`: If set to `true`, the [ReactDOM.hydrate](https://reactjs.org/docs/react-dom.html#hydrate) rendering component is used. The default value is `false`.
+  - `wrapper`: a react component that can be used to customize rendering logic.
+  - `queries`: customize some own `queries`.
+
+
+### Return Value
+
+- `{...queries}`: all available [queries](https://testing-library.com/docs/queries/about/)。
+- `container`: the DOM element that React component mounted.
+- `baseElement`
+- `debug`
+- `rerender`: if you want to test some scene when a rendered component is updated, you can use rerender for reality.
+- `unmount`: unmount rendered components. This API is helpful if you want to test what happens after the component is unmounted.
+- `asFragment`: return the [DocumentFragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) of rendered component. used to test the response of the DOM structure after the react event is triggered.
+
+
+## Example
+
+```ts
+import { render } from '@modern-js/runtime/testing';
+import App from './App';
+
+test('renders a message', () => {
+  const { container, getByText } = render(<App />);
+  expect(getByText('Hello, world!')).toBeInTheDocument();
+  expect(container.firstChild).toMatchInlineSnapshot(`
+    <h1>Hello, World!</h1>
+  `);
+});
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/testing/renderApp.md

@@ -0,0 +1,33 @@
+---
+title: renderApp
+---
+
+The `render` function is used to test normal components, and the `renderApp` function is used to test App components.
+
+## Usage
+
+```ts
+import { renderApp } from '@modern-js/runtime/testing';
+```
+
+App components refer to components that contain some Modern.js contexts, such as App root components, Containers using Models, etc.
+
+For the testing of such components, you can use the `renderApp` function, which will automatically wrap the context information according to the current `modern.config.js`.
+
+## Function Signature
+
+`renderApp` is the same as [render](./render.md).
+
+## Example
+
+```ts
+import { renderApp } from '@modern-js/runtime/testing';
+import App from './App';
+
+describe('test', () => {
+  it('test App', () => {
+    const { getByText } = renderApp(<App />);
+    expect(getByText('Hello Modern!')).toBeInTheDocument();
+  });
+});
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/utility/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Utility API",
+  "position": 10
+}

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/utility/css-in-js.md

@@ -0,0 +1,42 @@
+---
+title: CSS-In-JS API
+---
+
+Use Style Component to write CSS.
+
+## Usage
+
+```ts
+import styled from '@modern-js/runtime/styled';
+```
+
+## Function Signature
+
+see [styled-component API](https://styled-components.com/docs/api)。
+
+## Example
+
+```tsx
+import styled from '@modern-js/runtime/styled';
+
+const Button = styled.button`
+  background: palevioletred;
+  border-radius: 3px;
+  border: none;
+  color: white;
+`;
+
+const TomatoButton = styled(Button)`
+  background: tomato;
+`;
+
+function ButtonExample(){
+  return (
+    <>
+      <Button>I'm purple.</Button>
+      <br />
+      <TomatoButton>I'm red.</TomatoButton>
+    </>
+  );
+};
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/utility/head.md

@@ -0,0 +1,39 @@
+---
+title: Head
+---
+
+Used to add html elements (such as title, meta, script, etc.) to the `<head>` element, supports SSR.
+
+## Usage
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+
+export default () => (
+  <Helmet>...</Helmet>
+)
+```
+
+## Example
+
+```tsx
+import { Helmet } from '@modern-js/runtime/head';
+
+function IndexPage() {
+  return (
+    <div>
+      <Helmet>
+        <title>My page title</title>
+        <meta name="viewport" content="initial-scale=1.0, width=device-width" />
+      </Helmet>
+      <p>Hello Modern.js!</p>
+    </div>
+  )
+}
+
+export default IndexPage
+```
+
+## More
+
+For detail, see [react-helmet](https://github.com/nfl/react-helmet).

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/utility/loadable.md

@@ -0,0 +1,85 @@
+---
+title: loadable
+---
+
+Used to create Loadable component
+
+## Usage
+
+```ts
+import loadable from '@modern-js/runtime/loadable';
+```
+
+## Function Signature
+
+```ts
+type Options = {
+  resolveComponent?: (
+    module: Module,
+    props: Props,
+  ) => React.ComponentType<Props>,
+  fallback?: JSX.Element;
+  ssr?: boolean;
+}
+
+function loadable(loadFn: Function, options?: Options) => LoadableComponent
+```
+
+### Input
+
+#### loadFn
+
+Used to load component.
+
+```ts
+import loadable from '@modern-js/runtime/loadable';
+
+const OtherComponent = loadable(() => import('./OtherComponent'))
+```
+
+#### options.resolveComponent
+
+Type: `(module: Module, props: Props) => React.ComponentType<Props>`
+
+`module` is the component returned by `loadFn`, and `props` is the props parameter accepted by the component.
+
+By default, we think that the default export of file is a react component, so we can render the component directly. But when the component is named export, or we need to dynamically determine which component needs to be rendered according to the `props`, we can use `resolveComponent`. Here is an example:
+
+```ts title='component.js'
+export const Apple = () => 'Apple!'
+export const Orange = () => 'Orange!'
+```
+
+```ts title='loadable.js'
+const LoadableApple = loadable(() => import('./components'), {
+  resolveComponent: (components) => components.Apple,
+})
+const LoadableOrange = loadable(() => import('./components'), {
+  resolveComponent: (components) => components.Orange,
+})
+const LoadableFruit = loadable(() => import('./components'), {
+  resolveComponent: (components, props) => components[props.fruit],
+})
+```
+
+#### options.fallback
+
+Whether to display fallback content during loading.
+
+#### options.ssr
+
+Whether to support SSR, the default value is `true`。
+
+### Return Value
+
+#### LoadableComponent
+
+```ts
+type LoadableComponent<Props> =
+  React.ComponentType<
+    Props & { fallback?: JSX.Element; }>
+  & {
+    preload(props?: Props): void;
+    load(props?: Props): Promise<React.ComponentType<Props>>;
+  }
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/web-server/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Web Server API",
+  "position": 9
+}

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/web-server/hook.md

@@ -0,0 +1,131 @@
+---
+title: Hook
+---
+
+Used to extend Modern.js built-in Web Server, requests except BFF are handled by these hooks.
+
+:::note
+For more detail, see [Extend Web Server](/docs/guides/advanced-features/web-server)。
+:::
+
+## Usage
+
+```ts
+import { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatchHook = (context, next) => {}
+export const afterRender: AfterRenderHook = (context, next) => {}
+```
+
+:::info
+使用该 API 前，请先执行 `pnpm run new` 新建「Web Server 扩展」源码目录。
+
+```bash
+pnpm run new
+? 请选择你想要的操作 创建工程元素
+? 新建「Web Server 扩展」源码目录
+```
+:::
+
+## Function Signature
+
+```ts
+type HookContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    cookies: {
+      get: (key: string) => string;
+      set: (key: string, value: string) => void;
+      delete: () => void;
+      clear: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+  };
+  request: {
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+};
+
+function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
+```
+
+different Hooks additionally provide different contexts. Currently Modern.js support `AtferMatch` and `AfterRender`.
+
+```ts
+type AfterMatchContext = HookContext & {
+  router: {
+    redirect: (url: string, status: number) => void;
+    rewrite: (entry: string) => void;
+  };
+}
+
+type AfterRenderContext = {
+  template: {
+    get: () => string;
+    set: (html: string) => void;
+    prependHead: (fragment: string) => void;
+    appendHead: (fragment: string) => void;
+    prependBody: (fragment: string) => void;
+    appendBody: (fragment: string) => void;
+  };
+};
+```
+
+
+### Input
+
+- `context`: Hook context.
+  - `response`: provides a series of methods to process the response.
+  - `request`: provides a series of methods to get request info.
+  - `router`: provides methods on routing.
+  - `template`: provides methods on content.
+- `next`: call next listener（not affect the server process, only current hook）。
+
+## Example
+
+### Redirect
+
+Redirect to pages outside the site, for example to login page:
+
+```ts
+import type { AfterMatch } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatch = async (ctx, next) => {
+  ctx.router.redirect('https://website.com/login', 302);
+};
+```
+
+### Rewrite
+
+Rewrite to pages of the current site, for example, the same route returns pages that are adapted to different UA:
+
+```ts
+import type { AfterMatch } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatch = async (ctx, next) => {
+  ctx.router.rewrite('mobile');
+};
+```
+
+### HTML Inject
+
+Inject some HTML content to the page, such as scripts, page skeletons, etc.:
+
+```ts
+import type { AfterRender } from '@modern-js/runtime/server';
+
+export const afterRender: AfterRenderHook = (context, next) => {
+  ctx.template.prependBody('<div>Footer</div>');
+}
+```

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/web-server/middleware.md

@@ -0,0 +1,106 @@
+---
+title: Middleware
+---
+
+Used to extend Modern.js built-in Web Server, only SSR requests are handled by these middleware.
+
+Unlike [Hook](/docs/apis/app/runtime/web-server/hook), middleware can be extended using the framework plugin.
+
+:::note
+For more detail, see [Extend Web Server](/docs/guides/advanced-features/web-server)。
+:::
+
+## Usage
+
+```ts
+import { Middleware } from '@modern-js/runtime/server';
+
+export const middleware: Middleware = async (context, next) => {}
+export const middleware: Middleware[] = [
+  async (context, next) => {},
+  async (context, next) => {},
+]
+```
+
+:::info
+使用该 API 前，请先执行 `pnpm run new` 新建「Web Server 扩展」源码目录。
+
+```bash
+pnpm run new
+? 请选择你想要的操作 创建工程元素
+? 新建「Web Server 扩展」源码目录
+```
+:::
+
+## Function Signature
+
+```ts
+type MiddlewareContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    cookies: {
+      get: (key: string) => string;
+      set: (key: string, value: string) => void;
+      delete: () => void;
+      clear: () => void;
+      apply: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+    locals: Record<string, any>;
+  };
+  request: {
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+  source: {
+    req: IncomingMessage;
+    res: ServerResponse;
+  };
+};
+
+type RequestHandler = (context: Context, next: NextFunction) => Promise<void> | void;
+```
+
+
+### Input
+
+- `context`: Middleware context.
+  - `response`: provides a series of methods to process the response.
+  - `request`: provides a series of methods to get request info.
+  - `source`: provides Node.js native `req` and `res` object。
+- `next`: call next listener（not affect the server process, only current hook）。
+
+## Example
+
+### Tracking
+
+```ts
+export const Middleware = () => async (ctx, next) => {
+  const start = Date.now();
+  ctx.res.once('finish', () => {
+    console.log(Date.now() - start);
+  });
+}
+```
+
+### Inject Tools & Data
+
+Modern.js provides `res.locals` to store local variables for the current request.
+
+```ts
+export const Middleware = () => async (ctx, next) => {
+  ctx.res.locals.id = 'Modern.js';
+  ctx.res.locals.rpc = createRpcInstance();
+});
+```
+

package/en/docusaurus-plugin-content-docs/current/configure/app/bff/fetcher.md

@@ -0,0 +1,28 @@
+---
+sidebar_label: fetcher
+---
+
+# bff.fetcher
+
+* Type: `string`
+* Default:
+  * Brower：[global.fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+  * Node.js：[node-fetch](https://github.com/node-fetch/node-fetch)
+
+:::caution Caution
+First you need to enable the "BFF" function using [new](/docs/apis/app/commands/new) command.
+:::
+
+Custom `fetch` function, which can be used for `fetch` function customization in Native and Mini Program scenarios.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    fetcher: 'custom-fetch'
+  }
+});
+```
+
+:::info
+You need to judge the running environment when you implement the isomorphic fetch function.
+:::

package/en/docusaurus-plugin-content-docs/current/configure/app/bff/prefix.md

@@ -0,0 +1,33 @@
+---
+sidebar_label: prefix
+---
+
+# bff.prefix
+
+* Type: `string`
+* Default: `/api`
+
+:::caution Caution
+First you need to enable the "BFF" function using [new](/docs/apis/app/commands/new) command.
+:::
+
+By default, the route access BFF prefix's directory is `/api`, with the following directory structure:
+
+```bash
+api
+└── hello.ts
+```
+
+The corresponding route for `api/hello.ts` access is `localhost:8080/api/hello`.
+
+This configuration option can modify the default route prefix:
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    prefix: '/api-demo'
+  }
+})
+```
+
+The corresponding `api/hello.ts` access route is `localhost:8080/api-demo/hello`.

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

@@ -0,0 +1,75 @@
+---
+sidebar_label: proxy
+---
+
+# bff.proxy
+
+* Type: `Record<string, string>`
+* Default: `{}`
+
+:::caution Caution
+First you need to enable the "BFF" function using [new](/docs/apis/app/commands/new) command.
+:::
+
+With simple configuration, no code is required, Modern.js automatically forwards requests. Requests sent to Modern.js BFF server are proxied to the specified service.
+
+BFF Proxy uses the powerful [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware), and if you need more advanced usage, you can check its [documentation](https://github.com/chimurai/http-proxy-middleware#options).
+
+Add the following configuration to `modern.server-runtime.config.ts`, you can turn on the proxy:
+
+```typescript title="modern.server-runtime.config.ts"
+import { defineConfig } from '@modern-js/app-tools/server';
+export default defineConfig({
+  bff: {
+    proxy: {
+      "/api": "https://cnodejs.org"
+    }
+  }
+})
+```
+
+Assuming that the starting Modern.js BFF server's service address is `localhost:8080`, all requests whose path starts with `api` will be intercepted, such as requests sent to `localhost:8080/api/v1/topics` will be proxied to `https://cnodejs.org/api/v1/topics`.
+
+You can do path rewriting, such as proxying requests sent to `localhost:8080/api/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': {
+        target: 'https://cnodejs.org',
+        pathRewrite: { '/api/topics': '/api/v1/topics' },
+        changeOrigin: true,
+      },
+    },
+  },
+});
+```
+
+Unlike [dev.proxy](/docs/configure/app/dev/proxy), the proxy described in this section only works on requests entering the BFF/API service; at the same time, this configuration can be used not only in the development environment, but also in the production environment. The corresponding request will also be proxied in the production environment.
+
+## Common usage
+
+### Solve interface cross-domain problems
+
+In the process of project development, because web pages and interface services are not deployed under the same domain name, cross-domain problems are often encountered.
+
+There are many ways to solve cross-domain problems, and here we use `bff.proxy` to easily solve cross-domain problems.
+
+
+:::info
+In BFF proxy mode, if you do not need to write the BFF interface, the API directory can be deleted; at this time, BFF proxy will still be enabled.
+:::
+
+As shown below, in the `modern.server-runtime.config.js`, write the following configuration; we send all web pages to the same domain that request proxies starting with `/api` to another domain's service.
+
+```typescript title="modern.server-runtime.config.ts"
+export default defineServerConfig({
+  bff: {
+    proxy: {
+      '/api': 'https://cnodejs.org',
+    },
+  },
+};
+```

package/en/{configure → docusaurus-plugin-content-docs/current/configure}/app/dev/asset-prefix.md

@@ -1,7 +1,6 @@
 ---
 title: dev.assetPrefix
 sidebar_label: assetPrefix
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/en/{configure → docusaurus-plugin-content-docs/current/configure}/app/dev/hmr.md

@@ -1,7 +1,6 @@
 ---
 title: dev.hmr
 sidebar_label: hmr
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/en/{configure → docusaurus-plugin-content-docs/current/configure}/app/dev/https.md

@@ -1,7 +1,6 @@
 ---
 title: dev.https
 sidebar_label: https
-sidebar_position: 1
 ---
 
 :::info BUILDER

package/en/{configure → docusaurus-plugin-content-docs/current/configure}/app/dev/port.md

@@ -1,7 +1,6 @@
 ---
 title: dev.port
 sidebar_label: port
-sidebar_position: 1
 ---
 
 :::info BUILDER