@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/en/guides/basic-features/env-vars.mdx

@@ -0,0 +1,170 @@
+---
+title: Environment Variable
+sidebar_position: 7
+---
+# Environment Variable
+
+Modern.js provides support for environment variables, including built-in environment variables and custom environment variables.
+
+## Built-in Environment
+
+### NODE_ENV
+
+The current execution environment and is a **read-only** environment variable whose have different values under different execution commands:
+
+- `production`：the default value when exec `modern build` or `modern serve`.
+- `test`：the default value when exec `modern test`.
+- `development`：the default value when exec `modern dev`, alse the default value of other case.
+
+### MODERN_ENV
+
+Set the current execution environment manually. In addition to the values in the NODE_ENV, custom environment names are supported here, such as `staging`, `boe`, etc.
+
+:::tip
+MODERN_ENV priority is higher than NODE_ENV.
+
+:::
+
+### MODERN_TARGET
+
+Auto inject when use `@modern-js/runtime`，Used to distinguish between SSR and CSR environments. Developers can judge by themselves in the code, and dead code will be removed by default when building.
+
+```ts title="App.tsx"
+function App() {
+  if (process.env.MODERN_TARGET === 'browser') {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+In the development environment, you can see that the SSR and CSR bundles as follows:
+
+```js title="dist/bundles/main.js"
+function App() {
+  if (false) {
+  }
+}
+```
+
+```js title="dist/static/main.js"
+function App() {
+  if (true) {
+    console.log(window.innerHeight);
+  }
+}
+```
+
+:::note
+In a production environment, dead code is removed, such as the `if` statement above.
+
+:::
+
+This can provide different products for different client sides to ensure that the bundle size is minimized. It can also be convenient to deal with some side effects in the code in different environments.
+
+## Custom Environment Variables
+
+Custom environment variables can be specified in both `shell` and `.env` files.
+
+### Specify via `shell`
+
+Add custom environment variables before the command:
+
+```shell
+REACT_APP_FOO=123 BAR=456 pnpm run dev
+```
+
+### Specify via `.env` file
+
+Create a `.env` file in the project root and add custom environment variables, which are added to the Node.js process by default, for example:
+
+```bash
+REACT_APP_FOO=123
+BAR=456
+```
+
+The `.env` file follows the following loading rules:
+
+- `.env`：default.
+- `.env.{ MODERN_ENV | NODE_ENV }`：Setting environment variables for a specific environment overrides the same in `.env`.
+
+When you need to use different config according to the environment, you can define environment variables in the `.env` file corresponding to the environment name, and manually set the execution environment when starting the project.
+
+For example, when starting a project with the following command，the `.env` and `.env.staging` will load:
+
+```shell
+MODERN_ENV=staging pnpm run dev
+```
+
+## Using Environment Variables
+
+### Convention Names
+
+`NODE_ENV` can be used directly in front-end code. In addition, custom environment variables starting with `MODERN_` can also be used directly in code.
+
+For Example:
+
+```js
+if (process.env.NODE_ENV === 'development') {
+  // do something
+}
+```
+
+After executing the `pnpm run dev`, you can see the following bundle:
+
+```js
+if (true) {
+  // do something
+}
+```
+
+In custom HTML templates, you can also use such environment variables directly. For example, in `config/html/head.html`:
+
+```html
+<meta name="test" content="<process.env.NODE_ENV>" />
+```
+
+### Any Other Names
+
+If you need to use environment variables with any other names in your code，you can config [`source.globalVars`](/configure/app/source/global-vars), for example:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  source: {
+    globalVars: {
+      'process.env.VERSION': process.env.VERSION,
+    }.
+  },
+});
+```
+
+At this point, the `process.env.VERSION` in the code will be replaced with the value of `VERSION` in the environment variables.
+
+:::note
+`source.globalVars` also supports replacing other expressions or strings with specified values, not limited to environment variables.
+
+:::
+
+## Use Global Replacement
+
+In addition to environment variables, Modern.js also supports replacing variables in code with other values or expressions, which can be used like distinguish development environment and production environment in code.
+
+For example, converts the expression `TWO` to `1 + 1`:
+
+```ts
+export default {
+  source: {
+    define: {
+      TWO: '1 + 1',
+    },
+  },
+};
+```
+
+```ts
+const foo = TWO;
+
+// ⬇️ Turn into being...
+const foo = 1 + 1;
+```
+
+In most cases, `source.globalVars` is already sufficient to replace variables. But the values passed in by `source.globalVars` will be serialized by JSON by default. So it cannot be replaced like `1 + 1` in the example above，at this time, we need use [`source.define`](/configure/app/source/define)。

package/en/guides/basic-features/html.mdx

@@ -0,0 +1,247 @@
+---
+title: HTML Template
+sidebar_position: 9
+---
+# HTML Template
+
+Modern.js provides **JSX syntax** and **HTML(Ejs) syntax** for customizing HTML template.
+
+## JSX syntax
+
+Modern.js convention, in the `src/`, or in the entry directory, you can create `Document.[jt]sx` and export a component by default. The rendering result of this component can be used as an HTML template for the entry.
+
+For example the following directory structure:
+
+```bash
+.
+├── src
+│   ├── Document.tsx
+│   ├── entry-a
+│   │   ├── Document.tsx
+│   │   └── routes
+│   ├── entry-b
+│   │   └── routes
+│   └── modern-app-env.d.ts
+```
+
+`entry-a` will take precedence over the `Docoument.[jt]sx` file under the current entry. If the current entry does not have a `Document.[jt]sx` file, such as `entry-b`, it will look for the `Document.[jt]sx` file in the root directory.
+
+If not, it will go to the the logic of traditional templates.
+
+### HTML Component
+
+Modern.js provides a list of components for rendering pages to help developers generate templates, which can be exported from `@modern-js/runtime/document`:
+
+```tsx
+import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
+```
+
+These components are rendered:
+
+- `Html`：Provide the ability of native HTML Elements, and render necessary components that the developer did not add by default. `<Head>` and `<Body>` must exist, and other components can be assembled by selecting appropriate components on demand.
+
+- `Body`：Provide the ability of native Body Element, which needs to contain the `<Root>` component internally, and also supports other elements as child elements at the same time, such as adding footers.
+
+- `Root`：React root element `<div id='root'></div>`。the default element id is `id = 'root'`, can set `props.rootId` to change the id。Child components can be added, and will also be rendered into HTML templates, which will be overwritten when React rendering is complete, generally used to implement global Loading.
+
+- `Head`：Provides native Head Element capabilities and automatically populates `<meta>`, as well as the `<Scripts>` component.
+
+- `Scripts`：The script content generated by the webpack, which can be used to adjust the position of the bundle result, is placed in the `<Head>` component by default.
+
+### Template Params
+
+Because it is in the form of JSX, in `Document.[jt]sx`, you can use various variables in the component to assign values to various custom components more freely.
+
+At the same time, Modern.js provides `DocumentContext` to provide some configuration and environment parameters, The main parameters as follow:
+
+- `processEnv`：Provide build-time env vars.
+- `config`：The configuration of the project, only `output` are exposed.
+- `entryName`：current entry name.
+- `templateParams`：HTML template params(in order to be compatible with traditional templates, it is not recommended to use).
+
+### Examples
+
+```tsx
+import React, { useContext } from 'react';
+import {
+  Html,
+  Root,
+  Head,
+  Body,
+  Scripts,
+  DocumentContext,
+} from '@modern-js/runtime/document';
+
+export default function Document(): React.ReactElement {
+  // the params provide by DocumentContext
+  const {
+    config: { output: htmlConfig },
+    entryName,
+    templateParams,
+  } = useContext(DocumentContext);
+
+  return (
+    <Html>
+      <Head>
+        <link href="https://modernjs.dev">Modern.js</link>
+      </Head>
+      <Body>
+        <Root rootId="root">
+          <h1 style={{ color: 'red' }}>Some Params：</h1>
+          <h2> entryName：{entryName}</h2>
+          <h2> title：{htmlConfig.title}</h2>
+          <h2> rootId: {templateParams.mountId}</h2>
+        </Root>
+        <h1>bottom</h1>
+      </Body>
+    </Html>
+  );
+}
+```
+
+The above JSX component will generate the following HTML template:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <meta http-equiv="x-ua-compatible" content="ie=edge" />
+    <meta name="renderer" content="webkit" />
+    <meta name="layoutmode" content="standard" />
+    <meta name="imagemode" content="force" />
+    <meta name="wap-font-scale" content="no" />
+    <meta name="format-detection" content="telephone=no" />
+    <script>
+      ...
+    </script>
+    <script defer src="/static/js/lib-react.js"></script>
+    <script defer src="/static/js/lib-polyfill.js"></script>
+    <script defer src="/static/js/lib-router.js"></script>
+    <script
+      defer
+      src="/static/js/vendors-node_modules_pnpm_loadable_component_5_15_2_react_18_2_0_node_modules_loadable_compon-3fb0cf.js"
+    ></script>
+    <script
+      defer
+      src="/static/js/packages_runtime_plugin-router-legacy_dist_js_treeshaking_runtime_index_js-packages_runtime_p-28f4c9.js"
+    ></script>
+    <script defer src="/static/js/sub.js"></script>
+    <link href="https://www.baidu.com" />
+  </head>
+
+  <body>
+    <div id="root">
+      {/* <?- html ?> */}
+      <h1 style="color:red">Some Params：</h1>
+      <h2>entryName：sub</h2>
+      <h2>title：</h2>
+      <h2>rootId: root</h2>
+    </div>
+    <h1>bottom</h1>
+    {/* <?- chunksMap.js ?> */}
+    {/* <?- SSRDataScript ?> */}
+  </body>
+</html>
+```
+
+## Html Synxtax
+
+Modern.js also supports HTML syntax. By default, an HTML template is built into the Modern.js application project to generate HTML code.
+
+Based on HTML syntax templates, Modern.js provides **Custom HTML Fragments** and **Fully Custom HTML Templates** two ways to customize templates.
+
+### Custom HTML Fragments
+
+In the application root directory, create the `config/html/` directory, which supports the creation of four kinds of HTML fragments.
+
+- `top.html`
+- `head.html`
+- `body.html`
+- `bottom.html`
+
+**These fragments will be injected into the default HTML template.**
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <%= meta %>
+    <title><%= title %></title>
+    <%= topTemplate %>
+
+    <script>
+      window.__assetPrefix__ = '<%= assetPrefix %>';
+    </script>
+    <%= headTemplate %>
+    {/* webpack inject css  */}
+  </head>
+  <body>
+    <noscript>
+      We're sorry but react app doesn't work properly without JavaScript
+      enabled. Please enable it to continue.
+    </noscript>
+    <div id="<%= mountId %>"></div>
+    <%= bodyTemplate %>
+    {/* webpack inject js  */}
+    {/* <?- bottomTemplate ?> */}
+  </body>
+</html>
+```
+
+HTML Fragments support the use [Lodash template](https://lodash.com/docs/4.17.15#template)。
+
+For example, insert a script in `body.html`:
+
+```html title="config/html/body.html"
+<script src="//example.com/assets/a.js"></script>
+```
+
+:::info
+The implementation of the custom HTML fragment is to merge the fragment with the built-in template of the frame. Since `<title>` already exists in the default template of the frame, the `<title>` in the custom HTML template cannot take effect. Please pass [html.title](/configure/app/html/title) to modify the page title.
+
+:::
+
+### Fully Custom HTML Templates
+
+In some cases, HTML snippets do not meet the customization requirements, Modern.js provide a fully customized way.
+
+:::caution
+It is not recommended to override the default HTML template directly, and some features may be lost. Even if it needs to be replaced, it is recommended to build on the built-in template and modify it as needed.
+
+:::
+
+In the `config/html/` directory, create a index.html file that will override the default HTML template.
+
+:::info
+The internal default HTML template can be viewed in `node_modules/.modern-js/${entryName}/index.html`.
+
+:::
+
+### Template Params
+
+The parameters used in the template can be defined by the [html.templateParameters](/configure/app/html/template-parameters).
+
+### Config By Entry
+
+The fragment in the `config/html/` directory are valid for all entries in the application. If you want to customize the HTML by entry, you can create a new directory named with the **entry name** in the `config/html/` directory, and then customize the HTML snippets in this directory.
+
+For example, the following HTML fragment is only valid for `entry1`:
+
+```bash
+.
+├── config/
+│   └── html/
+│       └── entry1
+│           ├── head.html
+│           └── body.html
+└── src/
+    ├── entry1/
+    │   └── routes
+    └── entry2/
+        └── routes
+```

package/en/guides/basic-features/mock.mdx

@@ -0,0 +1,79 @@
+---
+title: Mock
+sidebar_position: 6
+---
+# Mock
+
+Modern.js provides the ability to quickly generate Mock data, allowing the front-end to develop independently without being blocked by the back-end interface.
+
+## Mock File
+
+By convention, when there is `index.[jt]s` in the `config/mock/` directory, the Mock Data will be automatically enabled, as follows:
+
+```bash
+.
+├── config
+│   └── mock
+│       └── index.ts
+├── src
+│   └── App.tsx
+└── modern.config.ts
+```
+
+## Writing Mock Files
+
+the `config/mock/index.ts` file only needs to export an object containing all Mock APIs. The properties of the object are composed of the request configuration `method` and `url`, and the corresponding property values can be `Object`, `Array`, `Function`:
+
+```js
+export default {
+  /* The attribute is the concrete method and request url, and the value is object or array as the result of the request */
+  'GET /api/getInfo': { data: [1, 2, 3, 4] },
+
+  /* the default method is GET */
+  '/api/getExample': { id: 1 },
+
+  /* You can use custom functions to dynamically return data */
+  'POST /api/addInfo': (req, res, next) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.end('200');
+  },
+};
+```
+
+when access `http://localhost:8080/api/getInfo`, the api will return json `{ "data": [1, 2, 3, 4] }`。
+
+## Return Random Data
+
+Libraries such as [Mock.js](https://github.com/nuysoft/Mock/wiki/Getting-Started) can be used in `config/mock/index.js` to generate random data, for example:
+
+```js
+const Mock = require('mockjs');
+
+module.exports = {
+  '/api/getInfo': Mock.mock({
+    'data|1-10': [{ name: '@cname' }],
+  }) /* => {data: [{name: "董霞"}, {name: "魏敏"},  {name: "石磊"}} */,
+};
+```
+
+:::info Other Mock Lib
+
+- [Chancejs](https://github.com/chancejs/chancejs)
+- [Mock](https://github.com/nuysoft/Mock/wiki/Getting-Started)
+
+:::
+
+## Delayed Return
+
+- It can be achieved using the function of the browser "weak connection simulation".
+- Delays can be set via `setTimeout`, for example:
+
+```ts
+export default {
+  'api/getInfo': (req, res) => {
+    setTimeout(() => {
+      res.end('delay 2000ms');
+    }, 2000);
+  },
+};
+```

package/en/guides/basic-features/proxy.mdx

@@ -0,0 +1,61 @@
+---
+title: Proxy
+sidebar_position: 5
+---
+# Proxy
+
+## Local Proxy
+
+Modern.js provides a way to configure the development proxy in ['tools.devServer'] (/docs/configure/app/tools/dev-server). For example, to proxy the local interface to an online address:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    devServer: {
+      proxy: {
+        '/go/api': {
+          target: 'http://www.example.com/',
+          changeOrigin: true,
+        },
+      },
+    },
+  },
+});
+```
+
+when access `http://localhost:8080/go/api`, the response content is returned from [http://www.example.com/](http://www.example.com/).
+
+:::info
+For more detail, see [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)。
+
+:::
+
+## Global Proxy
+
+import GlobalProxy from "@site-docs-en/components/global-proxy"
+
+<GlobalProxy />
+
+## BFF Proxy
+
+By configuring [`bff.proxy`](/configure/app/bff/proxy), you can proxy BFF API requests to specified services. Unlike other proxy above, it can also be used in the production environment:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    proxy: {
+      '/api/v1': 'https://cnodejs.org',
+    },
+  },
+});
+```
+
+For example, when a BFF call is used in the code, the final request `http://localhost:8080/api/v1/topics` will auto proxy to `https://cnodejs.org/api/v1/topics`：
+
+```js
+import getTopics from '@api/v1/topics';
+
+getTopics();
+```