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

@modern-js/main-doc 2.8.0 → 2.9.0

Files changed (1079) hide show

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

@@ -1,247 +0,0 @@
----
-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/proxy.mdx DELETED Viewed

@@ -1,61 +0,0 @@
----
-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/en/guides/get-started/introduction.mdx DELETED Viewed

@@ -1,34 +0,0 @@
----
-title: Introduction
-sidebar_position: 1
----
-# Introduction
-## Modern.js Introduction
-**Modern.js** is a progressive modern web development framework based on React.
-The framework has a variety of built-in out-of-the-box tools, excellent build performance, zero-configuration rendering paradigm switching, and integrated API calls. Starting from three solutions (Application solutions, Module solutions, Monorepo solutions), it supports front-end research and development of a complete period.
-Modern.js is ByteDance's underlying front-end framework, which has directly or indirectly served thousands of applications, including middle and back-end, PC Web, H5 and other application scenarios. The framework covers a full life cycle, has a complete plugin system, and provides a high degree of customization capabilities. Support custom solutions exclusive to business lines through generator plugin, customize various functional extensions and business requirements, and help developers build applications faster.
-## Why Modern.js
-Modern.js can provide developers with the ultimate **Development Experience**，make the app 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 support all the configuration and tools required by React applications, and have built-in **additional functions and optimizations**. 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 fetch, state management, etc.
-It mainly contains the following features:
-- 🪜 **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/en/guides/get-started/quick-start.mdx DELETED Viewed

@@ -1,162 +0,0 @@
----
-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
-```
-:::note
-Modern.js also supports package management with `yarn` and `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
-```
-## 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/en/guides/topic-detail/framework-plugin/extend.mdx DELETED Viewed

@@ -1,164 +0,0 @@
----
-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.