@modern-js/main-doc 2.1.0 → 2.3.0

package/en/apis/app/hooks/server/index_.mdx

@@ -0,0 +1,16 @@
+---
+title: index.[tj]s
+sidebar_position: 1
+---
+# index.[tj]s
+
+A file that extends the Modern.js Web Server, to add a Hook or Middleware to the Web Server that the project uses.
+
+It can intercept requests and responses, authenticate and role, request preprocessing, exception bottom-up, etc.;
+
+It can also be inserted logic into the built-in processing handler (including route matching, resource addressing, header injection, page rendering, static web hosting).
+
+:::info
+For detail, see [Hook](/apis/app/runtime/web-server/hook) & [Middleware](/apis/app/runtime/web-server/middleware)。
+
+:::

package/en/apis/app/hooks/server/test.mdx

@@ -0,0 +1,12 @@
+---
+title: test.[tj]s
+sidebar_position: 2
+---
+# test.[tj]s
+
+App's Web Server test file，support for writing test cases in the `server/` directory which file with suffix `.test.[tj]s`.
+
+:::info
+To use unit test and integration test, you need to execute the `new` command in advance to enable the `unit test/integration test`.
+
+:::

package/en/apis/app/hooks/shared.mdx

@@ -0,0 +1,7 @@
+---
+title: shared/
+sidebar_position: 5
+---
+# shared/
+
+Shared directory. When the project has common code under `api/`, `server/`, `src/`, put the code under this directory rather then import directly.

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

@@ -0,0 +1,54 @@
+---
+title: App.[tj]sx
+sidebar_position: 1
+---
+# App.[tj]sx
+
+Entry identifier if App want control route by code.
+
+`App.[tj]sx` is not the actual App entry, Modern.js will auto generate the entry file, the content is roughly as follows:
+
+```js
+import React from 'react';
+import { createApp, bootstrap } from '@modern-js/runtime';
+// App.[jt]sx
+import App from '@_modern_js_src/App';
+import { state } from '@modern-js/runtime/plugins';
+import {
+  immer,
+  effects,
+  autoActions,
+  devtools,
+} from '@modern-js/runtime/model';
+
+const createStatePlugins = config => {
+  const plugins = [];
+  plugins.push(immer(config['immer']));
+  plugins.push(effects(config['effects']));
+  plugins.push(autoActions(config['autoActions']));
+  plugins.push(devtools(config['devtools']));
+  return plugins;
+};
+let AppWrapper = null;
+function render() {
+  AppWrapper = createApp({
+    plugins: [
+      state({
+        ...{ plugins: createStatePlugins(true) },
+        ...App?.config?.state,
+      }),
+    ],
+  })(App);
+  if (IS_BROWSER) {
+    bootstrap(AppWrapper, MOUNT_ID);
+  }
+  return AppWrapper;
+}
+AppWrapper = render();
+export default AppWrapper;
+```
+
+:::note
+In multi-entry App，each entry can have a `App.[jt]sx`, for detail, see [Entry](/guides/concept/entries).
+
+:::

package/en/apis/app/hooks/src/index_.mdx

@@ -0,0 +1,34 @@
+---
+title: index.[tj]s
+sidebar_position: 4
+---
+# index.[tj]s
+
+Entry identifier if App want use custom entry. In most case, [`App.[tj]sx`](/apis/app/hooks/src/app) hook file can already meet our needs.
+
+When we need to add custom behavior before `bootstrap` or completely take over the webpack entry, we can place `index.[tj]s` in `src/` or entry directory. The following are discussed in two cases:
+
+1. add custom behavior before bootstrap
+
+Just add default export under `src/index.[tj]s`:
+
+```js title=src/index.js
+import { bootstrap } from '@modern-js/runtime';
+
+export default App => {
+  // do something before bootstrap...
+  bootstrap(App, 'root');
+};
+```
+
+2. Fully take over the webpack entry
+
+When there is no default export function under `src/index.[tj]sx?`, this file is the real webpack entry file, and the code can be organized such as create-react-app:
+
+```js title=src/index.jsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import App from './App';
+
+ReactDOM.render(<App />, document.getElementById('root'));
+```

package/en/apis/app/hooks/src/pages.mdx

@@ -0,0 +1,182 @@
+---
+title: pages/
+sidebar_position: 3
+---
+# pages/
+
+Entry identifier if the application want uses file system-based routing.
+
+When the entry is the **Pages entry** type, the files in the `pages/` directory will be analyzed to client side routing.
+
+For example, the following directory:
+
+```bash
+.
+└── src
+    └── pages
+        ├── about
+        │   └── index.jsx
+        ├── index.jsx
+        └── info.jsx
+```
+
+The generated route is configured as:
+
+```bash
+[
+  { path: '/', component: 'pages/index.jsx' },
+  { path: '/info' component: 'pages/info.jsx' },
+  { path: '/about', component: 'pages/about/index.jsx' }
+]
+```
+
+Files match the following conditions will not be treated as routing files:
+
+- suffix is not `.(j|t)sx?`.
+- `.d.ts` type definition file.
+- test file suffix like `.(test|spec|e2e).(j|t)sx?`.
+
+:::tip
+it is recommended to write only the routing files in the `pages/`, and write the business logic to the independent features directory outside the `pages/`. In this way, most of the files in the pages directory will be routing files, and there is no need for additional filtering rules.
+
+:::
+
+### Dynamic Routing
+
+Directories or files wrapped with `[]` are considered dynamic routing.
+
+For example the following directory structure:
+
+```bash
+.
+└── src
+    └── pages
+        ├── [post]
+        │   ├── detail.jsx
+        │   └── index.js
+        ├── users
+        │   └── [id].jsx
+        ├── index.jsx
+        └── info.jsx
+```
+
+The generated route is configured as:
+
+```js
+[
+  { path: '/', component: 'pages/index.jsx' },
+  { path: '/info', component: 'pages/info.jsx' },
+  { path: '/:post/', component: 'pages/[post]/index.js' },
+  { path: '/:post/detail' components: 'pages/[post]/detail.jsx'},
+  { path: '/users/:id', components: 'pages/users/[id].jsx'}
+]
+```
+
+Basis dynamic routing, it supports adding special routing suffixes `(*、?、+)`.
+
+For example: `src/pages/users/[id]*.tsx` generate route `/users/:id*`
+
+### Global Layout
+
+When the entire App needs a global `layout`, it can be achieved through `pages/_app.tsx`, which as follows:
+
+```js
+import React from 'react';
+import UserLayout from 'xxxx';
+
+export default const App = ({Component, ...pageProps}:{ Component: React.ComponentType}) => {
+  return (
+    <UserLayout>
+      <Component {...pageProps} />
+    </UserLayout>
+  );
+}
+```
+
+The above `Component` is the component to which the route is accessed.
+
+For example the following directory structure:
+
+```bash
+.
+└── pages
+    ├── a
+    │   ├── b
+    │   │   └── index.js
+    │   └── index.js
+    └── index.js
+```
+
+- access `/`, the `Component` is `pages/index.js`。
+- access `/a`, the `Component` is `pages/a/index.js`。
+- access `/a/b`, the `Component` is `pages/a/b/index.js`。
+
+:::tip Advantages
+
+- preserve the state of the global layout when the page changes.
+- add global css.
+- handle ComponentDidCatch error
+- use `defineConfig`(/docs/apis/app/runtime/app/define-config) dynamic configuration runtime.
+
+:::
+
+### Partial Layout
+
+When developing an App, where sub routes under the same route may share the layout.
+
+For this scene, Modern.js convention, when there is a `_layout.js` in the directory, the routes can shared this layout.
+
+For example the following directory structure:
+
+```bash
+└── pages
+    ├── a
+    │   ├── b
+    │   │   └── index.js
+    │   ├── _layout.js
+    │   └── index.js
+    └── index.js
+```
+
+```js title="pages/a/_layout.js"
+import React from 'react';
+
+const ALayout = ({ Component, ...pageProps }) => {
+  return <Component {...pageProps} />;
+};
+export default ALayout;
+```
+
+The Component props is the specific route, for example
+
+- access `/a`, the `Component` is `pages/a/index.js`。
+- 访问 `/a/b`, the `Component` is `pages/a/b/index.js`。
+
+In this way, you can use `pages/a/_layout.js` to display the routing common layout in the `a` directory.
+
+### 404 路由
+
+The convention `pages/404.[tj]sx` is the default 404 route.
+
+For example the following directory structure:
+
+```bash
+.
+└── src
+    └── pages
+        ├── user.js
+        ├── home.js
+        ├── 404.js
+```
+
+the generated route is configured is as:
+
+```bash
+[
+ { path: '/user', component: './pages/user.js'},
+ { path: '/home', component: './pages/home.js' },
+ { path: '*', component: './pages/404.js'}
+]
+```
+
+All unmatched routes will match to `pages/404.[tj]s`。

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

@@ -0,0 +1,90 @@
+---
+title: routes/
+sidebar_position: 2
+---
+# routes/
+
+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](/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](/apis/app/runtime/router/#useparams).
+
+In the loader, params will be used as input to [loader](/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/apis/app/hooks/src/server.mdx

@@ -0,0 +1,34 @@
+---
+title: '*.[server|node].[tj]sx'
+sidebar_position: 8
+---
+# *.[server|node].[tj]sx
+
+Used in application projects to place server side code, it generally has the following two functions：
+
+1. When `*.tsx` and `*. [server|node].tsx` coexist, rendering on the server side will give preference to the `*. [server|node].tsx` file instead of the `*.tsx` file.
+
+2. When using [data loader](/guides/basic-features/data-fetch), the server-side dependencies need to be re-exported from this file
+
+```tsx
+// routes/user/avatar.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+import { readFile } from './utils.server';
+
+type ProfileData = {
+  /* some type declarations */
+};
+
+export const loader = async (): ProfileData => {
+  const profile = await readFile('profile.json');
+  return profile;
+};
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+
+// routes/user/utils.server.ts
+export * from 'fs-extra';
+```

package/en/apis/app/hooks/src/stories.mdx

@@ -0,0 +1,14 @@
+---
+title: '**/*.stories.[tj]sx'
+sidebar_position: 7
+---
+# **/*.stories.[tj]sx
+
+App Storybook debug file. files in `src/` which suffix `*.stories.[tj]sx` are as debug files for Storybook.
+
+Execute the `dev story` command to debugging these files in the Storybook.
+
+:::info
+Using a Storybook requires executing `new` command to enable the 「Visual Testing (Storybook)」 mode.
+
+:::

package/en/apis/app/hooks/src/test.mdx

@@ -0,0 +1,14 @@
+---
+title: '**/*.test.[tj]sx?'
+sidebar_position: 6
+---
+# **/*.test.[tj]sx?
+
+App test file.
+
+The App supports the file suffixed with `.test.[tj]sx` under the `src/` to write test cases.
+
+:::info
+To use unit test and integration test, you need to execute the `new` command in advance to enable the `unit test/integration test`.
+
+:::

package/en/apis/app/runtime/app/define-config.mdx

@@ -0,0 +1,61 @@
+---
+title: defineConfig
+---
+# defineConfig
+
+For dynamically configuring applications runtime features.
+
+## Usage
+
+```ts
+import { defineConfig } from '@modern-js/runtime';
+```
+
+Runtime configurations can usually be configured under the `runtime` of the `modern.config.js`, such as the [router](/configure/app/runtime/router) configuration.
+
+The configuration in `modern.config.js` is determined at build time，If some configuration parameters are obtained at runtime, or if the configuration parameters are from a module (such as a component), then need use `defineConfig` API configuration on runtime.
+
+:::info
+`@modern-js/app-tools` has the same name API, Used to provide **TS type for configuration**, please distinguish them.
+
+:::
+
+## Function Signature
+
+```ts
+function defineConfig(Component, config): any;
+```
+
+### Input
+
+- Component: App root Component。
+- config: runtime config。
+
+## Example
+
+```tsx
+function App () {
+  ...
+}
+
+defineConfig(App, {
+  router: {
+    supportHtml5History: false
+  }
+})
+```
+
+1. `defineConfig` can configuring [runtime.state](/configure/app/runtime/state)、[runtime.router](/configure/app/runtime/router) etc.
+
+2. `defineConfig` before configuring a property, such as `router`, you need to make sure that the `modern.config.js` has been configured to enable this feature.
+
+3. `defineConfig` incoming configuration will be merged with the configuration in `modern.config.js`. Taking `router` as an example, the final application configuration is as follows:
+
+```json
+{
+  // 来自 `modern.config.js`
+  ...runtime.router
+  // 来自 `defineConfig`
+  ...config.router
+}
+```

package/en/apis/app/runtime/bff/hook.mdx

@@ -0,0 +1,44 @@
+---
+title: hook
+---
+# hook
+
+Used to add framework middleware under BFF function mode, the middleware will execute before BFF function.
+
+## Usage
+
+according to the framework extend plugin, export from the corresponding namespace:
+
+```ts
+import { hook } from '@modern-js/runtime/{namespace}';
+```
+
+## Function Signature
+
+```ts
+type HookOptions = {
+  addMiddleware: string | function;
+};
+
+function hook(options: HookOptions): void;
+```
+
+### Input
+
+- `options`: a range of hooks provided by Modern.js.
+  - `addMiddleware`: add middlewares for BFF.
+
+## Example
+
+middleware for different frameworks should be different(an example is when using the koa framework):
+
+```ts title=api/_app.ts
+import { hook } from '@modern-js/runtime/koa';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (ctx, next) => {
+    ctx.req.query.id = 'koa';
+    await next();
+  });
+});
+```

package/en/apis/app/runtime/bff/use-context.mdx

@@ -0,0 +1,38 @@
+---
+title: useContext
+---
+# useContext
+
+Used to get the request context in the BFF function.
+
+## Usage
+
+according to the framework extend plugin, export from the corresponding namespace:
+
+```ts
+import { useContext } from '@modern-js/runtime/{namespace}';
+```
+
+## Function Signature
+
+`function useContext(): any`
+
+## Example
+
+Developers can get more request information through `context`, such as browser UA(an example is when using the koa framework):
+
+```ts
+import { useContext } from '@modern-js/runtime/koa';
+
+export async function get() {
+  const ctx = useContext();
+  return ctx.req.headers['user-agent'];
+}
+```
+
+:::caution
+only in BFF function, `useContext` API can be used.
+
+:::
+
+Although the `useContext` API is supported in any framework extend plugin, the types of return values are different.

package/en/apis/app/runtime/core/bootstrap.mdx

@@ -0,0 +1,70 @@
+---
+title: bootstrap
+---
+# bootstrap
+
+Used to start and mount App, usually without manual calls。This API is only required when using [Custom App](/guides/concept/entries#自定义-app).
+
+## Usage
+
+```ts
+import ReactDOM from 'react-dom/client';
+import { bootstrap } from '@modern-js/runtime';
+
+bootstrap(App, 'root', undefined, ReactDOM);
+```
+
+## Function Signature
+
+```ts
+type BootStrap<T = unknown> = (
+  App: React.ComponentType,
+  id: string | HTMLElement | RuntimeContext,
+  root?: any,
+  ReactDOM?: {
+    render?: Renderer;
+    hydrate?: Renderer;
+    createRoot?: typeof createRoot;
+    hydrateRoot?: typeof hydrateRoot;
+  },
+) => Promise<T>;
+```
+
+### Input
+
+- `AppComponent`: reactElement instance created by [`createApp`](./create-app).
+- `rootId`: DOM root element id to mount，like `"root"`.
+- `root`: ReactDOM.create the return value, which is used in the scenario where the root needs to destroy the component outside the bootstrap function.
+- `ReactDOM`: ReactDOM object for distinguishing between React 18 and React 17 APIs.
+
+## Example
+
+```tsx
+import ReactDOM from 'react-dom/client';
+import { createApp, bootstrap } from '@modern-js/runtime';
+
+function App() {
+  return <div>Hello Modern.js</div>;
+}
+
+const WrappedApp = createApp({
+  // customized plugin
+  plugins: [customPlugin()],
+})(App);
+
+bootstrap(WrappedApp, 'root', undefined, ReactDOM);
+```
+
+:::info
+since `@modern-js/runtime/plugins` is a alias，when used in a ts project, its type needs to be declared，Just add the following type declarations to `src/modern-app-env.d.ts`:
+
+```ts
+declare module '@modern-js/runtime/plugins';
+```
+
+:::
+
+:::warning
+bootstrap only supported for use in CSR.
+
+:::