npm - @modern-js/main-doc - Versions diffs - 2.8.0 → 2.10.0 - Mend

@modern-js/main-doc 2.8.0 → 2.10.0

Files changed (1096) hide show

package/docs/en/guides/basic-features/html.mdx ADDED Viewed

@@ -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/docs/en/guides/basic-features/proxy.mdx ADDED Viewed

@@ -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](/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();
+```

package/docs/en/guides/get-started/introduction.mdx ADDED Viewed

@@ -0,0 +1,50 @@
+---
+title: Introduction
+sidebar_position: 1
+---
+# Introduction to Modern.js
+**Modern.js is an open source web engineering system from ByteDance**, which provides multiple solutions to help developers solve problems in different development scenarios.
+Currently, Modern.js includes three solutions, each targeting at different development scenarios: web application development, npm package development, and document site development:
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/Solutions-en-0945.png)
+As a part of the Modern.js engineering system, each of these solutions can be used separately and has its own independent documentation site. Developers can choose one or more solutions as needed.
+## About Documentation
+**This documentation site corresponds to the Modern.js framework**, which is used to developing web applications.
+- If you are developing an npm package, please refer to the [Modern.js Module](https://modernjs.dev/module-tools/en) documentation.
+- If you are developing a document site, please refer to the [Modern.js Doc](https://modernjs.dev/doc-tools) documentation.
+- If you want to use the Modern.js's builder engine to implement a web framework, please refer to the [Modern.js Builder](https://modernjs.dev/builder/en) documentation.
+:::tip
+As the Modern.js framework is the most widely used, in this documentation site, we will omit the "framework" and simply call it as Modern.js.
+:::
+## Modern.js Framework
+**The Modern.js framework is a progressive web framework based on React**. At ByteDance, we use Modern.js to build upper-level frameworks that have supported the development of thousands of web applications.
+Modern.js can provide developers with the ultimate **development experience**, making the application get better **user experience**.
+In the process of developing React applications, developers often need to design implementations for certain functions, or use other libraries and frameworks to solve these problems.
+Modern.js supports all the configuration and tools required by React applications, and has additional features and optimisations built in. Developers can use React to build the UI of the application, and then gradually adopt Modern.js functions to solve common application requirements, such as routing, data fetching, state management, etc.
+It mainly contains the following features:
+- 🚀 **Rust Bundler**: Easily switch to Rspack bundler with faster build speed.
+- 🪜 **Progressive**: Create projects with the most streamlined templates, gradually turn on plugin capabilities through generators, and customize solutions.
+- 🏠 **Integration**: The development is unique to the production environment Web Server, CSR and SSR are isomorphic development, and the function as the API service call.
+- 📦 **Out Of The Box**: Default TS support, built-in build core, ESLint, debugging tools, full functionality can be tested.
+- 🌏 **Ecology**: Self-developed state management, micro frontend, module packaging, Monorepo solution and other peripheral requirements.
+- 🕸 **Routing Modes**: Contains controlled routing, routing based on file conventions (nested routing), configurable routing, etc.
+- 🚀 **Independently Build Core**: Support a variety of packaging tools, deep optimization bundle.
+## Next
+If you want to know how to use Modern.js, you can try [Create your first app](/tutorials/first-app/c01-start), or read [Quick Start](/guides/get-started/quick-start).

package/docs/en/guides/get-started/quick-start.mdx ADDED Viewed

@@ -0,0 +1,164 @@
+---
+title: Quick Start
+sidebar_position: 2
+---
+# Quick Start
+## Environment
+### Node.js
+Requires [Node.js LTS](https://github.com/nodejs/Release) and ensures that the Node version is greater than or equal to 14.19.0, 16.x version is recommended.
+Modern.js recommend installing [nvm](https://github.com/nvm-sh/nvm#install--update-script) in the development environment and integrating [script to automatically switch node versions](https://github.com/nvm-sh/nvm#deeper-shell-integration) in the shell.
+Then there is a `.nvmrc` file with the content of `lts/fermium` or `lts/gallium` in the root directory of the repository, it will automatically install or switch to the correct Node.js version when entering the repository.
+### pnpm
+[pnpm](https://pnpm.io/installation) is recommended for package management.
+```bash
+npm install -g pnpm@7
+```
+:::note
+Modern.js also supports other package managers, such as `yarn` or `npm`.
+:::
+## Installation
+Modern.js provides the `@modern-js/create` tool to create projects. Don't install globally, use `npx` to run on demand.
+Projects can be created using an existing empty directory:
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create
+```
+Projects can also be created directly from the new directory:
+```bash
+npx @modern-js/create myapp
+```
+## Initialize
+import InitApp from "@site-docs-en/components/init-app"
+<InitApp />
+## Development
+Execute `pnpm run dev` in the project to start the project:
+```bash
+$ pnpm run dev
+> modern dev
+info    Starting dev server...
+info    App running at:
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+ Client ✔ done in 76.10ms
+```
+Open `http://localhost:8000/` in your browser and you will see the following:
+![dev](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/dev.png)
+## Configuration
+The `modern.config.ts` files exist in Modern.js projects created by the generator.
+Features can be enabled through the configuration file, or the default behavior of the coverage Modern.js. For example, add the following configuration to enable SSR:
+```ts
+import { defineConfig } from '@modern-js/app-tools';
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+});
+```
+Re-execute `pnpm run dev`, in the browser Network menu, you can find that the project has completed page rendering at the server level.
+## Build
+Execute `pnpm run build` in the project to build the project production environment product:
+```bash
+$ pnpm run build
+> modern build
+info    Create a production build...
+info    File sizes after production build:
+  File                                      Size         Gzipped
+  dist/static/js/lib-corejs.ffeb7fb8.js     214.96 kB    67.23 kB
+  dist/static/js/lib-react.09721b5c.js      152.61 kB    49.02 kB
+  dist/static/js/218.102e2f39.js            85.45 kB     28.5 kB
+  dist/static/js/lib-babel.a7bba875.js      11.93 kB     3.95 kB
+  dist/html/main/index.html                 5.84 kB      2.57 kB
+  dist/static/js/main.3568a38e.js           3.57 kB      1.44 kB
+  dist/static/css/async/304.c3c481a5.css    2.62 kB      874 B
+  dist/asset-manifest.json                  1.48 kB      349 B
+  dist/static/js/async/304.c45706bc.js      1.4 kB       575 B
+  dist/static/js/async/509.fcb06e14.js      283 B        230 B
+ Client ✔ done in 3.57s
+```
+The bundle is generated to `dist/` by default, and the directory structure is as follows:
+```
+.
+├── asset-manifest.json
+├── html
+│   └── main
+├── loader-routes
+│   └── main
+├── modern.config.json
+├── route.json
+└── static
+    ├── css
+    └── js
+```
+> If you want to customize the output directory, please refer to [Output Files](https://modernjs.dev/builder/en/guide/basic/output-files.html).
+## Verify
+Execute `pnpm run serve` in the project to verify locally that the bundle is running correctly:
+```bash
+$ pnpm run serve
+> modern serve
+Starting the modern server...
+info    App running at:
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+Open http://localhost:8000/ in the browser and the content should be the same as when `pnpm run dev`.
+## Deploy
+After the local verification is completed, the products under `dist/` can be organized into the structure required by the server for deployment.

package/docs/en/guides/topic-detail/framework-plugin/extend.mdx ADDED Viewed

@@ -0,0 +1,164 @@
+---
+title: Extending
+sidebar_position: 5
+---
+# Extending Plugin Hooks
+This section describes how to extend plugin Hooks by dynamically registering [Hook models](/guides/topic-detail/framework-plugin/hook).
+## Example
+Here is a simple example to demonstrate how to extend plugin Hooks by adding Hooks that manage console output.
+First, we initialize an empty project file and add basic dependencies:
+```bash
+$ npx @modern-js/create modern-js-demo
+```
+### Creating Hooks
+First, let's create a Hook model:
+```ts title=config/plugin/myPlugin.ts
+import { createWaterfall } from '@modern-js/plugin';
+const message = createWaterfall<string[]>();
+```
+then register:
+```ts title=config/plugin/myPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+  registerHook: {
+    message,
+  },
+});
+```
+add Hook types:
+```ts title=config/plugin/myPlugin.ts
+declare module '@modern-js/core' {
+  export interface Hooks {
+    message: typeof message;
+  }
+}
+```
+### Using Hooks
+Create a plugin and add command handling logic through the `commands` Hook function:
+```ts title=config/plugin/myPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+  setup(api) {
+    return {
+      commands({ program }) {
+        program.command('message').action(async () => {
+          const hookRunners = api.useHookRunners();
+          const messages = hookRunners.message([]);
+          console.log(messages.join('\n'));
+        });
+      },
+    };
+  },
+});
+```
+now `config/plugin/myPlugin.ts` is:
+```ts title=config/plugin/myPlugin.ts
+import { createWaterfall } from '@modern-js/plugin';
+import type { CliPlugin } from '@modern-js/core';
+const message = createWaterfall<string[]>();
+export default (): CliPlugin => ({
+  name: 'my-plugin',
+  registerHook: {
+    message,
+  },
+  setup(api) {
+    return {
+      commands({ program }) {
+        program.command('message').action(async () => {
+          const hookRunners = api.useHookRunners();
+          const messages = hookRunners.message([]);
+          console.log(messages.join('\n'));
+        });
+      },
+    };
+  },
+});
+declare module '@modern-js/core' {
+  export interface Hooks {
+    message: typeof message;
+  }
+}
+```
+Then add this plugin in `modern.config.ts`:
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import myPlugin from './config/plugin/myPlugin';
+export default defineConfig({
+  plugins: [myPlugin()],
+});
+```
+Now, run `npx modern message`, and the related logic will be executed, but no information is collected, so the console output is empty.
+add:
+```ts title=config/plugin/otherPlugin.ts
+import type { CliPlugin } from '@modern-js/core';
+export default (): CliPlugin => ({
+  name: 'other-plugin',
+  setup(api) {
+    return {
+      message(list) {
+        return [...list, '[foo] line 0', '[foo] line 1'];
+      },
+    };
+  },
+});
+```
+add to config:
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import myPlugin from './config/plugin/myPlugin';
+import otherPlugin from './config/plugin/otherPlugin';
+export default defineConfig({
+  plugins: [myPlugin(), otherPlugin()],
+});
+```
+run `npx modern message`, then we can get follow in console:
+```bash
+$ modern message
+[foo] line 0
+[foo] line 1
+```
+By using the above approach, you can extend plugin Hooks with various capabilities.