@modern-js/app-tools 3.7.0 → 3.8.0

package/docs/guides/basic-features/debug/mock.md

@@ -0,0 +1,109 @@
+# Data Mocking
+
+Modern.js allows you to easily generate mock data so that the front-end can develop independently without depending on the back-end API.
+
+## Enabling Mock
+
+By convention, when there is an `index.ts` in the `config/mock/` directory, mock data will be automatically enabled:
+
+```bash
+.
+├── config
+│   └── mock
+│       └── index.ts
+├── src
+│   └── App.tsx
+└── modern.config.ts
+```
+
+You can use [`dev.mockDir`](/configure/app/dev/mock-dir.md) to place the
+Mock entry in another directory:
+
+```js title="modern.config.ts"
+export default {
+  dev: {
+    mockDir: './mocks',
+  },
+};
+```
+
+## 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`, or `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, req and res are both Node.js HTTP objects. */
+  'POST /api/addInfo': (req, res, next) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.end('200');
+  },
+};
+```
+
+When you 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: "Jack"}, {name: "Jim"},  {name: "Mary"}} */,
+};
+```
+
+:::info Other Mock Libraries
+
+- [Chancejs](https://github.com/chancejs/chancejs)
+- [Mock](https://github.com/nuysoft/Mock/wiki/Getting-Started)
+
+:::
+
+## Delayed Response
+
+- You can do this by using the browser's "weak connection simulation" feature.
+- Delays can be set via `setTimeout`, for example:
+
+```ts
+export default {
+  '/api/getInfo': (req, res) => {
+    setTimeout(() => {
+      res.end('delay 2000ms');
+    }, 2000);
+  },
+};
+```
+
+## Use Mock On Demand
+
+Under the `config/mock/index.ts`, you can also export the `config` to control the Mock service.
+
+```ts
+import type { IncomingMessage } from 'node:http';
+import type { ServerResponse } from 'node:http';
+
+type MockConfig = {
+  enable: ((req: IncomingMessage, res: ServerResponse) => boolean) | boolean;
+};
+
+export const config = {
+  enable: false
+}
+```
+
+Currently only the `enable` configuration is supported, which allows developers to control whether to execute mock.
+
+:::note
+After modifying `config`, there is no need to restart the service, which will take effect immediately.
+:::

package/docs/guides/basic-features/debug/proxy.md

@@ -0,0 +1,21 @@
+# Local Proxy
+
+Modern.js provides a way to configure the development proxy in [`dev.server.proxy`](/configure/app/dev/server.md).
+
+For example, to proxy the local interface to another address:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  dev: {
+    server: {
+      proxy: {
+        // http://localhost:8080/api -> https://example.com/api
+        // http://localhost:8080/api/foo -> https://example.com/api/foo
+        '/api': 'https://example.com',
+      },
+    },
+  },
+});
+```

package/docs/guides/basic-features/debug/rsdoctor.md

@@ -0,0 +1,62 @@
+# Using Rsdoctor
+
+Rsdoctor is a Rspack build analysis tool. In Modern.js, we recommend using Rsdoctor to diagnose and analyze the build process and build outputs.
+
+## Install Dependencies
+
+
+```sh [npm]
+npm add @rsdoctor/rspack-plugin -D
+```
+
+```sh [yarn]
+yarn add @rsdoctor/rspack-plugin -D
+```
+
+```sh [pnpm]
+pnpm add @rsdoctor/rspack-plugin -D
+```
+
+```sh [bun]
+bun add @rsdoctor/rspack-plugin -D
+```
+
+```sh [deno]
+deno add npm:@rsdoctor/rspack-plugin -D
+```
+
+## Register Plugin
+
+In `modern.config.ts`, you can register the Rspack plugin via `tools.bundlerChain`. Refer to the example below:
+
+```ts title="modern.config.ts"
+import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';
+
+export default {
+  // ...
+  tools: {
+    bundlerChain(chain) {
+      // Only register the plugin when RSDOCTOR is true, as the plugin will increase build time.
+      if (process.env.RSDOCTOR) {
+        chain.plugin('rsdoctor').use(RsdoctorRspackPlugin, [
+          {
+            // Plugin options
+          },
+        ]);
+      }
+    },
+  },
+};
+```
+
+## Execute Build
+
+You can execute the build command within your project. After the build is complete, Rsdoctor will automatically open the analysis page for the build.
+
+```bash
+RSDOCTOR=true npm run build
+```
+
+## Related Documentation
+
+For more information, please refer to the [Rsdoctor Website](https://rsdoctor.rs/).

package/docs/guides/basic-features/debug/using-storybook.md

@@ -0,0 +1,112 @@
+# Using Storybook
+
+[Storybook](https://storybook.js.org/) is a tool specifically designed for component debugging. It provides:
+
+- A rich variety of debugging capabilities
+- Integration with some testing tools
+- Reusable documentation content
+- Sharing capabilities
+- Workflow automation
+
+## Principle
+
+Rsbuild provides [Storybook Rsbuild](https://storybook.rsbuild.rs/index.html), which allows any Rsbuild project to use this tool for building Storybook.
+
+Modern.js implements `storybook-addon-modernjs` based on this tool. This plugin loads the Modern.js configuration file and converts it into a configuration usable by **Storybook Rsbuild**.
+
+:::info
+This document only provides the simplest usage. For more information, please refer to [Storybook Rsbuild Modern.js Integration](https://storybook.rsbuild.rs/guide/integrations/modernjs.html).
+:::
+
+## Installation
+
+
+```sh [npm]
+npm install @rsbuild/core storybook-builder-rsbuild storybook-addon-modernjs -D
+```
+
+```sh [yarn]
+yarn add @rsbuild/core storybook-builder-rsbuild storybook-addon-modernjs -D
+```
+
+```sh [pnpm]
+pnpm add @rsbuild/core storybook-builder-rsbuild storybook-addon-modernjs -D
+```
+
+```sh [bun]
+bun add @rsbuild/core storybook-builder-rsbuild storybook-addon-modernjs -D
+```
+
+```sh [deno]
+deno add npm:@rsbuild/core npm:storybook-builder-rsbuild npm:storybook-addon-modernjs -D
+```
+
+You need to install `@rsbuild/core` in your project, otherwise the plugin may not work properly.
+
+## Configure `.storybook/main.ts`
+
+```ts
+import type { StorybookConfig } from 'storybook-react-rsbuild'
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: ['storybook-addon-modernjs'],
+  framework: 'storybook-react-rsbuild',
+}
+export default config
+```
+
+## BFF Integrated Calls in Storybook
+
+When you want to call BFF APIs directly in Storybook components (for example `/api/**`), start the BFF service and configure a proxy in Storybook's dev server to avoid CORS issues.
+
+### 1. Add scripts
+
+Add the following scripts to `package.json` to start the BFF server and Storybook separately. The `BFF_PROXY` environment variable ensures the proxy is only enabled during Storybook build:
+
+```json
+{
+  "scripts": {
+    "dev:api": "modern dev --api-only",
+    "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
+  }
+}
+```
+
+### 2. Configure proxy
+
+Add the following config in `modern.config.ts` to proxy requests to the BFF service only during Storybook build:
+
+```ts
+export default applyBaseConfig({
+  dev: process.env.BFF_PROXY
+    ? {
+        server: {
+          proxy: {
+            '/api': 'http://localhost:8080',
+          },
+        },
+      }
+    : {},
+});
+```
+
+Proxy path and port follow this logic:
+
+- If `dev.server.proxy` is configured, use that configuration
+- If not configured, the proxy path falls back to `bff.prefix`, otherwise `/api`
+- If not configured, the target port falls back to `server.port`, otherwise `8080`
+- The final target is `http://localhost:<port>`
+
+### 3. Start
+
+```bash
+pnpm dev:api
+pnpm storybook
+```
+
+Now you can request the path configured in `bff.prefix`; if not configured, use `/api/**`.
+
+## Example
+
+You can check out the [example](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react) to learn how to use Storybook in Modern.js.