@modern-js/main-doc 2.1.0 → 2.3.0

package/en/configure/app/tools/style-loader.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: styleLoader
+---
+
+# tools.styleLoader
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [tools.styleLoader](https://modernjs.dev/builder/en/api/config-tools.html#tools-styleloader)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/tools/styleLoader.md'
+
+<Main />

package/en/configure/app/tools/styled-components.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: styledComponents
+---
+
+# tools.styledComponents
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [tools.styledComponents](https://modernjs.dev/builder/en/api/config-tools.html#tools-styledcomponents)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/tools/styledComponents.md'
+
+<Main />

package/en/configure/app/tools/swc.mdx

@@ -0,0 +1,54 @@
+---
+title: tools.swc
+sidebar_label: swc
+---
+# swc
+
+- **Type:** `Object`
+- **Default:** `undefined`
+
+## Introduction
+
+[SWC](https://SWC.rs/) (Speedy Web Compiler) is a transformer and minimizer for JavaScript and TypeScript based on `Rust`. SWC can provide the same abilities with Babel, and it's more than 10x faster than Babel.
+
+Modern.js Builder has a out-of-box plugin for SWC, power your Web application with Polyfill and minification, we also port some common used Babel plugins to SWC.
+
+## Install
+
+The `@modern-js/plugin-swc` plugin needs to be installed before use.
+
+```bash
+pnpm add @modern-js/plugin-swc -D
+```
+
+After the installation，please register the SWC plugin in the `modern.config.ts` file, then the SWC compilation and compression will be enabled.
+
+```ts title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import swcPlugin from '@modern-js/plugin-swc';
+
+export default defineConfig({
+  plugins: [appTools(), swcPlugin()],
+});
+```
+
+## Config
+
+You can set the SWC compilation behavior through the `tools.swc` config.
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    swc: {
+      jsMinify: {
+        compress: {},
+        mangle: true,
+      },
+    },
+  },
+});
+```
+
+For config details, please refer to [Modern.js Builder - SWC Plugin Configuration](https://modernjs.dev/builder/en/plugins/plugin-swc.html#config).

package/en/configure/app/tools/tailwindcss.mdx

@@ -0,0 +1,35 @@
+---
+sidebar_label: tailwindcss
+---
+
+# tools.tailwindcss
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const tailwind = {
+  content: [
+    './config/html/**/*.html',
+    './config/html/**/*.ejs',
+    './config/html/**/*.hbs',
+    './src/**/*.js',
+    './src/**/*.jsx',
+    './src/**/*.ts',
+    './src/**/*.tsx',
+    './storybook/**/*',
+  ],
+  // Use source.design System config as Tailwind CSS theme config
+  theme: source.designSystem,
+};
+```
+
+When the value is of type `Object`, rhe configuration corresponding to [TailwindCSS](https://tailwindcss.com/docs/configuration) is merged with the default configuration through `Object.assign`.
+
+When the value is of type `Function`, the object returned by the function is merged with the default configuration by `Object.assign`.
+
+### Limitations
+
+The `theme` attribute is not allowed, otherwise the build will fail. Modern.js use [source.designSystem](/configure/app/source/design-system) as the Tailwind CSS Theme configuration.
+
+Other uses are consistent with [Tailwind CSS](https://tailwindcss.com/docs/configuration)。

package/en/configure/app/tools/terser.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: terser
+---
+
+# tools.terser
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [tools.terser](https://modernjs.dev/builder/en/api/config-tools.html#tools-terser)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/tools/terser.md'
+
+<Main />

package/en/configure/app/tools/ts-checker.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: tsChecker
+---
+
+# tools.tsChecker
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [tools.tsChecker](https://modernjs.dev/builder/en/api/config-tools.html#tools-tschecker)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/tools/tsChecker.md'
+
+<Main />

package/en/configure/app/tools/ts-loader.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: tsLoader
+---
+
+# tools.tsLoader
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [tools.tsLoader](https://modernjs.dev/builder/en/api/config-tools.html#tools-tsloader)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/tools/tsLoader.md'
+
+<Main />

package/en/configure/app/tools/webpack-chain.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: webpackChain
+---
+
+# tools.webpackChain
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [tools.webpackChain](https://modernjs.dev/builder/en/api/config-tools.html#tools-webpackchain)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/tools/webpackChain.md'
+
+<Main />

package/en/configure/app/tools/webpack.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: webpack
+---
+
+# tools.webpack
+
+:::tip
+This config is provided by Modern.js Builder, more detail can see [tools.webpack](https://modernjs.dev/builder/en/api/config-tools.html#tools-webpack)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/en/config/tools/webpack.md'
+
+<Main />

package/en/configure/app/usage.mdx

@@ -0,0 +1,139 @@
+---
+sidebar_position: 0
+---
+
+# Configure to use
+
+There are two configurations in the Modern.js, a compile configuration and a server runtime configuration.
+
+The compile configuration can be configured in two places:
+
+- `modern.config.(ts|js|mjs)` file in the root path
+- `package.json` file
+
+:::info
+Configurations in both package.json and modern.config.ts file are not supported for the same configuration. Configuration in modern.config.ts is recommended.
+:::
+
+Server runtime configuration can be configured in the `modern.server-runtime.config.(ts|js|mjs)` file in the root path.
+
+## Configure in the configuration file
+
+Modern.js configuration files are defined in the root path of the project, and supports `.js`, `.ts` and `.mjs` formats:
+
+- `modern.config.js`
+- `modern.config.ts`
+- `modern.config.mjs`
+
+### modern.config.js
+
+You can use JavaScript syntax in the `modern.config.js` file and it is more flexible than in the `package.json` file.
+
+For example, you can define configuration options for function types in `modern.config.js`:
+
+```js title="modern.config.js"
+export default {
+  source: {
+    alias: opts => {
+      opts['@common'] = './src/common';
+    },
+  },
+};
+```
+
+You can also dynamically set it with `process.env.NODE _ENV`:
+
+```js title="modern.config.js"
+export default {
+  server: {
+    ssr: process.env.NODE_ENV === 'development',
+  },
+};
+```
+
+### modern.config.ts (recommended)
+
+We recommend using configuration files in `.ts` format, which provides friendly TypeScript type hints to help you avoid configuration errors.
+
+Import the `defineConfig` tool function from `@modern-js/app-tools`, which will help you with configuration type derivation and type completion:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+});
+```
+
+## Configure in package.json (not recommended)
+
+In addition to configuration files, configuration options can also be set the `modernConfig` field in the `package.json`, such as:
+
+```json title="package.json"
+{
+  "modernConfig": {
+    "source": {
+      "alias": {
+        "@common": "./src/common"
+      }
+    }
+  }
+}
+```
+
+Due to the limitation of the JSON file format, only simple types such as numbers, strings, boolean values, arrays, etc. can be defined in `package.json`. When we need to set the value of the function type, it is recommended to set it in the Modern.js configuration file.
+
+### Note
+
+- It is not recommended to use both `package.json` and `modern.config.t[j]s` for configuration. If both are used and a configuration conflict occurs, Modern.js will prompt error on the command line.
+- `@modern-js/runtime` exports the [defineConfig](/apis/app/runtime/app/define-config) API of the same name, please pay attention to the distinction.
+
+## Debug configuration locally
+
+To facilitate local debugging configuration locally, Modern.js supports creating `modern.config.local.(ts|js|mjs)` files in the root directory of the project to override `modern.config.(ts|js|mjs)` configurations.
+
+### Example
+
+For example, the port number is configured as `3000` in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+If you need to change the port number to `3001` to debugging locally, but you don't want to change the `modern.config.ts` file of the current project, you can create a `modern.config.local.ts` file and add the following configuration:
+
+```ts title="modern.config.local.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3001,
+  },
+});
+```
+
+The configuration in the `modern.config.local.ts` file will be deep merged with the configuration in `modern.config.ts` and override the configurations in `modern.config.ts`, so `server.port` will be is overridden by `3001`.
+
+### Note
+
+When using `modern.config.local.ts`, please note the following:
+
+- The `modern.config.local.ts` file is only loaded when running `modern dev` or `modern start` commands, and will not be loaded when running `modern build`.
+- The `modern.config.local.ts` file overrides not only over `modern.config.ts`, but also the `modernConfig` field in `package.json`.
+- As `modern.config.local.ts` is only used for local debugging, it is not recommended to commit it to the repository, please ensure that the project's `.gitignore` file contains `modern.config.local.ts`.
+
+```bash title=".gitingore"
+modern.config.local.ts
+modern.config.local.js
+modern.config.local.mjs
+```

package/en/guides/advanced-features/bff/bff-proxy.mdx

@@ -0,0 +1,30 @@
+---
+sidebar_position: 5
+title: Use Proxy
+---
+# Use Proxy
+
+By configuring the BFF proxy, API requests can be forwarded without manual coding
+
+:::caution
+Using a BFF proxy ensures that requests can enter the BFF handler. (eg the request path must contain a bff prefix)
+
+:::
+
+Writing the following BFF proxy configuration in the `modern.server-runtime.config.js` file will proxy requests sent to `http://localhost:8080/api/v1/topics` to `https://cnodejs.org/api/v1/topics`.
+
+```js title="modern.server-runtime.config.js"
+import { defineConfig } from '@modern-js/app-tools/server';
+export default defineConfig({
+  bff: {
+    proxy: {
+      '/api/v1/topics': 'https://cnodejs.org',
+    },
+  },
+};
+```
+
+:::note
+For more detail, see [bff.proxy](/configure/app/bff/proxy)。For more proxy info, see [Proxy](/guides/basic-features/proxy)。
+
+:::

package/en/guides/advanced-features/bff/frameworks.mdx

@@ -0,0 +1,152 @@
+---
+sidebar_position: 3
+title: Frameworks
+---
+# Frameworks
+
+Modern.js's BFF supports different runtime frameworks, currently Modern.js's BFF supports two runtime frameworks[Express.js](https://expressjs.com/) 和 [Koa.js](https://koajs.com/).
+
+## Function Writing
+
+Under the function writing, only the middleware writing method of various runtime frameworks is different, and other implementations are basically the same. Take Express as an example to introduce how to write a middleware by hand in the `api/_ app.ts` and add permission verification:
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+import { Request, Response, NextFunction } from 'express';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req: Request, res: Response, next: NextFunction) => {
+    if (req.url !== '/api/login') {
+      const sid = req?.cookies?.sid;
+      if (!sid) {
+        res.status(400);
+        res.json({ code: -1, message: 'need login' });
+      } else {
+        next();
+      }
+    } else {
+      next();
+    }
+  });
+});
+```
+
+然后添加一个普通的 BFF 函数 `/api/hello.ts`:
+
+```ts
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
+
+Finally, add the access code of the interface in the front-end `src/App.tsx`, and call it directly in an integrated way:
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchMyApi() {
+      const { message } = await hello();
+      setText(message);
+    }
+
+    fetchMyApi();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+Then exec `pnpm run dev` starts the project, and accessing `http://localhost:8080/` will find that the request for'/api/hello 'is blocked:
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+
+Finally, modify the front-end code `src/App.tsx` to call the login interface before accessing `/api/hello`:
+
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+import { post as login } from '@api/login';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchAfterLogin() {
+      const { code } = await login();
+      if (code === 0) {
+        const { message } = await hello();
+        setText(message);
+      }
+    }
+    fetchAfterLogin();
+  }, []);
+
+  return <p>{text}</p>;
+};
+```
+
+Refresh the page and you can see that `/api/hello` was accessed successfully:
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
+
+The above code simulates the way to add middleware to the `/api/_app.ts` to achieve an easy login function. Also, other functions can be implemented in this hook file to extend BFF Server.
+
+## Framework Writing
+
+Under the framework writing, Modern.js does not collect middleware in the `api/_app.ts`, and the running process is controlled by the plugin itself.
+
+### Express
+
+The framework writing of Express supports defining the startup logic of API Server in `api/app.[tj]s`. performing the initialization work of the application, adding global middleware, declaring routes, and even extending the original framework.
+
+The route defined by the BFF function will be registered after the route defined by the `app.ts` file, so here you can also intercept the route defined by the BFF function, preprocess or respond in advance.
+
+```ts title="api/app.ts"
+import express from 'express';
+
+const app = express();
+
+app.put('/user', function (req, res) {
+  res.send('Got a PUT request at /user');
+});
+
+app.use(async (req, res, next) => {
+  console.info(`access url: ${req.url}`);
+  next();
+});
+
+export default app;
+```
+
+### Koa
+
+The Koa framework is written in a similar way to Express. It supports defining the startup logic of API Server in `app.[tj]s`, performing the initialization work of the application, adding global middleware, declaring routes, extending the original framework, etc.
+
+The route defined by the BFF function will be registered after the route defined by the `app.ts` file, so here you can also intercept the route defined by the BFF function, preprocess or respond in advance.
+
+:::caution
+Use the framework writing, when there is no `app.ts`, Modern.js will add koa-body by default. When there is `app.ts`, if the developer wants to use the BFF function with Body, he needs to ensure that the koa-body middleware has been added.
+
+:::
+
+```ts title=api/app.ts
+import koa from 'koa';
+
+const app = new Koa();
+
+app.put('/user', function (req, res) {
+  res.send('Got a PUT request at /user');
+});
+
+app.use(async (ctx, next) => {
+  console.info(`access url: ${ctx.url}`);
+  await next();
+});
+
+export default app;
+```