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

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

@@ -0,0 +1,14 @@
+---
+title: index.[tj]s
+sidebar_position: 1
+---
+
+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](/docs/apis/app/runtime/web-server/hook) & [Middleware](/docs/apis/app/runtime/web-server/middleware)。
+:::

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/server/test.md

@@ -0,0 +1,10 @@
+---
+title: test.[tj]s
+sidebar_position: 2
+---
+
+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/docusaurus-plugin-content-docs/current/apis/app/hooks/shared.md

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

package/en/docusaurus-plugin-content-docs/current/apis/app/hooks/src/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "src/",
+  "position": 1
+}

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

@@ -0,0 +1,45 @@
+---
+title: App.[tj]sx
+sidebar_position: 1
+---
+
+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](/docs/guides/concept/entries).
+:::
+

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

@@ -0,0 +1,34 @@
+---
+title: index.[tj]s
+sidebar_position: 3
+---
+
+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.
+
+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/docusaurus-plugin-content-docs/current/apis/app/hooks/src/pages.md

@@ -0,0 +1,180 @@
+---
+title: pages/
+sidebar_position: 2
+---
+
+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/docusaurus-plugin-content-docs/current/apis/app/hooks/src/stories.md

@@ -0,0 +1,12 @@
+---
+title: "**/*.stories.[tj]sx"
+sidebar_position: 7
+---
+
+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/docusaurus-plugin-content-docs/current/apis/app/hooks/src/test.md

@@ -0,0 +1,12 @@
+---
+title: "**/*.test.[tj]sx?"
+sidebar_position: 6
+---
+
+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/docusaurus-plugin-content-docs/current/apis/app/overview.md

@@ -0,0 +1,12 @@
+---
+sidebar_position: 0
+---
+
+# Overview
+
+This section covers all APIs in `@modern-js/app-tools`.
+
+import OverviewNav from '@site/src/components/OverviewNav';
+import sidebarData from '@site/plugins/overview-loader!@site/plugins/overview-data.json';
+
+<OverviewNav cards={sidebarData.docsSidebars.apisAppSidebar} />

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

@@ -0,0 +1,9 @@
+{
+  "label": "运行时",
+  "position": 3,
+  "collapsed": false,
+  "link": {
+    "type": "doc",
+    "id": "apis/app/runtime/index"
+  }
+}

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

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

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/app/define-config.md

@@ -0,0 +1,60 @@
+---
+title: 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](/docs/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](/docs/configure/app/runtime/state)、[runtime.router](/docs/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/docusaurus-plugin-content-docs/current/apis/app/runtime/bff/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "BFF API",
+  "position": 8
+}

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

@@ -0,0 +1,43 @@
+---
+title: 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/docusaurus-plugin-content-docs/current/apis/app/runtime/bff/use-context.md

@@ -0,0 +1,36 @@
+---
+title: 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/docusaurus-plugin-content-docs/current/apis/app/runtime/core/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Core API",
+  "sidebar-labale": "111",
+  "position": 3
+}

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/bootstrap.md

@@ -0,0 +1,55 @@
+---
+title: bootstrap
+---
+
+Used to start and mount App, usually without manual calls。This API is only required when using [Custom App](/docs/guides/advanced-features/custom-app).
+
+## Usage
+
+```ts
+import { bootstrap } from '@modern-js/runtime';
+
+bootstrap(App, 'root');
+```
+
+## Function Signature
+
+```ts
+function bootstrap(AppComponent: React.ComponentType<any>, rootId: string): React.ComponentType<any> | void
+```
+
+### Input
+
+- `AppComponent`: reactElement instance created by [`createApp`](./create-app).
+- `rootId`: DOM root element id to mount，like `"root"`.
+
+## Example
+
+```tsx
+import { createApp, bootstrap } from '@modern-js/runtime';
+import { router, state } from '@modern-js/runtime/plugins';
+
+function App() {
+  return <div>Hello Modern.js</div>;
+}
+
+const WrappedApp = createApp({
+  // customized plugin
+  plugins: [router({}), state({})],
+})(App);
+
+bootstrap(WrappedApp, 'root');
+
+```
+
+:::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.
+:::

package/en/docusaurus-plugin-content-docs/current/apis/app/runtime/core/create-app.md

@@ -0,0 +1,47 @@
+---
+title: createApp
+---
+
+Used to create custom entries, custom runtime plugins. This API is only required when using [Custom App](/docs/guides/advanced-features/custom-app).
+
+## Usage
+
+```ts
+import { createApp } from '@modern-js/runtime';
+```
+
+## Function Signature
+
+```ts
+import type { Plugin } from '@modern-js/runtime';
+
+function createApp(options: { plugins: Plugin[] }): React.ComponentType<any>;
+```
+
+### Input
+
+- `options`: optional configuration.
+  - `plugins`: custom plugin extensions.
+
+## Example
+
+### Create Custom Entry
+
+For details, see [`bootstrap`](./bootstrap.md)。
+
+### Custom Plugins
+
+```ts
+import { createApp } from '@modern-js/runtime';
+
+function App() {
+  return <div>app</div>;
+}
+
+export default createApp({
+  plugins: [
+    router({}),
+    state({}),
+  ]
+})(App);
+```