@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.8.1-ultramodern.1

package/docs/configure/app/usage.md

@@ -0,0 +1,276 @@
+# Configuration
+
+There are three types of configurations in Modern.js: Compile configuration, Runtime configuration, and Server Runtime configuration.
+
+**Compile configuration** can be configured in two locations:
+
+- The `modern.config.(ts|js|mjs)` file at the root path
+- The `package.json` file
+
+:::info
+Modern.js does not support configuring the same configuration item in both `package.json` and `modern.config.ts` simultaneously. It is recommended to configure it in `modern.config.ts`. If Modern.js detects conflicts due to duplicate configurations, it will throw a warning.
+:::
+
+**Runtime configuration** can be configured in the `src/modern.runtime.(ts|js|mjs)` file.
+
+**Server Runtime configuration** can be configured in the `server/modern.server.(ts|js|mjs)` file.
+
+## Compile Configuration
+
+### Configuring in Configuration Files
+
+The configuration files for Modern.js are defined in the root directory of the project and support `.ts`, `.js`, and `.mjs` formats:
+
+- `modern.config.ts`
+- `modern.config.js`
+- `modern.config.mjs`
+
+#### modern.config.ts (Recommended)
+
+We recommend using the `.ts` format for configuration files as it provides friendly TypeScript type hints, helping you avoid errors in the configuration.
+
+Import the `defineConfig` utility function from `@modern-js/app-tools`, which will assist you with type inference and type completion for the configuration:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+});
+```
+
+#### modern.config.js
+
+If you are developing a non-TypeScript project, you can use the `.js` format for the configuration file:
+
+```js title="modern.config.js"
+export default {
+  source: {
+    alias: opts => {
+      opts['@common'] = './src/common';
+    },
+  },
+};
+```
+
+You can also configure different settings based on the environment using `process.env.NODE_ENV`:
+
+```js title="modern.config.js"
+export default {
+  server: {
+    ssr: process.env.NODE_ENV === 'development',
+  },
+};
+```
+
+#### Exporting Configuration Functions
+
+Modern.js supports exporting a function in the configuration file, where you can dynamically compute the configuration and return it to Modern.js.
+
+```js title="modern.config.js"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig(({ env, command }) => ({
+  source: {
+    alias: {
+      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
+    },
+  },
+}));
+```
+
+This function accepts the following parameters:
+
+- `env`: Corresponds to the value of `process.env.NODE_ENV`.
+  - When running `modern dev`, the value of `env` is `development`.
+  - When running `modern build` or `modern serve`, the value of `env` is `production`.
+- `command`: Corresponds to the current command being run, such as `dev`, `build`, or `serve`.
+
+#### Exporting Asynchronous Functions
+
+Modern.js also supports exporting an asynchronous function in the configuration file, allowing you to perform some asynchronous operations:
+
+```js title="modern.config.js"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig(async ({ env, command }) => {
+  const result = await someAsyncFunction();
+
+  return {
+    html: {
+      title: result,
+    },
+  };
+});
+```
+
+#### Specifying Configuration Files
+
+The Modern.js command line supports specifying the name of the configuration file using the `--config` option.
+
+For example, if you need to use the `modern.prod.config.js` file when executing the `build` command, you can add the following configuration in `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "dev": "modern dev",
+    "build": "modern build --config modern.prod.config.js"
+  }
+}
+```
+
+You can also abbreviate the `--config` option as `-c`:
+
+```bash
+$ modern build -c modern.prod.config.js
+```
+
+### Configuring in package.json (Not Recommended)
+
+In addition to configuration files, you can also set configuration items under the `modernConfig` field in `package.json`, such as:
+
+```json title="package.json"
+{
+  "modernConfig": {
+    "source": {
+      "alias": {
+        "@common": "./src/common"
+      }
+    }
+  }
+}
+```
+
+Due to the limitations of the JSON file format, only simple types such as numbers, strings, booleans, and arrays can be defined in `package.json`. When we need to set function-type values, it is recommended to do so in the Modern.js configuration file.
+
+#### Notes
+
+- It is not recommended to use both `package.json` and `modern.config.js` for configuration simultaneously. If both are used and conflicts arise, Modern.js will prompt an error in the command line.
+
+### Local Debugging Configuration
+
+To facilitate local debugging of configurations, Modern.js supports creating a `modern.config.local.(ts|js|mjs)` file in the root directory to override the configuration options in `modern.config.(ts|js|mjs)`.
+
+#### Example
+
+For example, if the `modern.config.ts` file in your project is configured with a port number of `3000`:
+
+```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` for local debugging but do not want to modify the current project's `modern.config.ts` file, 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 deeply merged with the configuration in `modern.config.ts`, overriding the options in `modern.config.ts`, so `server.port` will be changed to `3001`.
+
+#### Notes
+
+When using `modern.config.local.ts`, please note the following:
+
+- The `modern.config.local.ts` file will only be loaded when executing the `modern dev` commands and will not be loaded during `modern build`.
+- The priority of the `modern.config.local.ts` file is higher than both `modern.config.ts` and the `modernConfig` field in `package.json`.
+- Since `modern.config.local.ts` is only used for local debugging, it is not recommended to commit it to the code repository. Ensure that the project's `.gitignore` file includes `modern.config.local.ts` and similar files.
+
+```bash title=".gitignore"
+modern.config.local.*
+```
+
+### Merging Multiple Configurations
+
+In some cases, you may need to merge multiple configurations into one. You can use the `mergeConfig` utility function to merge multiple configurations.
+
+The `mergeConfig` function accepts an array as a parameter, where each item in the array is a configuration object. `mergeConfig` will deeply merge each configuration object in the array, automatically merging multiple function items into an array, and finally returning a merged configuration object.
+
+#### Example
+
+```ts title="modern.config.ts"
+import { mergeConfig } from '@modern-js/app-tools';
+
+const config1 = {
+  dev: {
+    port: 3000,
+  },
+  tools: {
+    postcss: () => console.log('config1');
+  },
+};
+const config2 = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: () => console.log('config2');
+  },
+};
+
+const mergedConfig = mergeConfig([config1, config2]);
+```
+
+In the above example, the merged configuration object will be:
+
+```ts
+const mergedConfig = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: [() => console.log('config1'), () => console.log('config2')],
+  },
+};
+```
+
+### Configuration Type Definitions
+
+Modern.js exports the `AppUserConfig` type, which corresponds to the type of the Modern.js configuration object:
+
+```ts title="modern.config.ts"
+import type { AppUserConfig } from '@modern-js/app-tools';
+
+const config: AppUserConfig = {
+  tools: {
+    rspack: {},
+  },
+};
+```
+
+## Runtime Configuration
+
+For detailed information on runtime configuration, please refer to the [Introduction to Runtime Configuration](/configure/app/runtime/0-intro.md).
+
+:::tip
+If the current Runtime configuration needs to be used both at compile time and runtime, please add the relevant configuration parameters at the plugin registration location.
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import { xxPlugin } from '@modern-js/plugin-xx';
+
+export default defineConfig({
+  plugins: [
+    xxPlugin({
+      /** Add parameters here */
+    }),
+  ],
+});
+```
+
+:::

package/docs/guides/advanced-features/bff/cross-project.md

@@ -0,0 +1,109 @@
+# Cross-Project Invocation
+
+Based on the BFF architecture, Modern.js provides cross-project invocation capabilities, allowing BFF functions created in one project to be invoked by other projects through integrated calls, enabling function sharing and feature reuse across projects.
+Cross-project invocation consists of **producer** and **consumer** sides. The producer is responsible for creating and providing BFF services while generating integrated invocation SDK, and the consumer initiates requests through these SDK.
+
+## BFF Producer
+
+Enable cross-project invocation via configuration. Projects with BFF capabilities enabled can act as BFF producers, or you can create standalone BFF applications.
+When executing `dev` or `build`, the following artifacts for consumers will be automatically generated:
+
+- API functions under the `dist/client` directory
+- Runtime configuration functions under the `dist/runtime` directory
+- Interface exports defined in `exports` field of `package.json`
+- File list for npm publication specified in `files` field of `package.json`
+
+### Existing BFF-enabled Projects
+
+1. Enable Cross-Project Invocation
+
+Ensure the current project has BFF enabled with API files defined under `api/lambda`. Add the following configuration:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  }
+});
+```
+
+2. Generate SDK Type Files
+
+To provide type hints for the integrated invocation SDK, enable the `declaration` option in TypeScript configuration:
+
+```ts title="tsconfig.json"
+"compilerOptions": {
+    "declaration": true,
+}
+```
+
+## BFF Consumer
+
+:::info
+You can initiate requests to BFF producers from projects using any framework via the SDK.
+:::
+
+### Intra-Monorepo Invocation
+
+When producer and consumer are in the same Monorepo, directly import the SDK. API functions reside under `${package_name}/api`:
+
+```ts title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as hello } from '${package_name}/api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    hello().then(setText);
+  }, []);
+  return <div>{text}</div>;
+};
+```
+
+### Cross-Project Invocation
+
+When producer and consumer are in separate repositories, publish the BFF producer as an npm package. The invocation method remains the same as intra-Monorepo.
+
+### Domain Configuration and Extensions
+
+For real-world scenarios requiring custom BFF service domains, use the configuration function:
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+
+configure({
+  setDomain() {
+    return 'https://your-bff-api.com';
+  },
+});
+```
+
+The `configure` function from `${package_name}/runtime` supports domain configuration via `setDomain`, interceptors, and custom SDK. When extending both **current project** and **cross-project** SDK on the same page:
+
+```ts title="src/routes/page.tsx"
+import { configure } from '${package_name}/runtime';
+import { configure as innerConfigure } from '@modern-js/plugin-bff/client';
+import axios from 'axios';
+
+configure({
+    setDomain() {
+        return 'https://your-bff-api.com';
+    },
+});
+
+innerConfigure({
+  async request(...config: Parameters<typeof fetch>) {
+    const [url, params] = config;
+    const res = await axios({
+      url: url as string,
+      method: params?.method as Method,
+      data: params?.body,
+      headers: {
+        'x-header': 'innerConfigure',
+      },
+    });
+    return res.data;
+  },
+});
+```

package/docs/guides/advanced-features/bff/data-platform.md

@@ -0,0 +1,116 @@
+# Data Platform
+
+Modern.js Effect API runtime now supports a request-envelope based data platform contract for safer and more predictable data orchestration in complex applications such as Module Federation and micro frontends.
+
+## What it solves
+
+- Stable operation identity across host and remote applications.
+- Cache key isolation by namespace, origin, and user/tenant scope.
+- Envelope integrity checks for request payload + selection plan.
+- Optional strict envelope enforcement at the server boundary.
+- Safer cross-namespace invalidation (opt-in only).
+- Trace context continuity for distributed observability.
+
+## Runtime contract helpers
+
+Use `@modern-js/plugin-bff/data-platform` helpers to build and validate contracts:
+
+```ts
+import {
+  createOperationId,
+  buildScopeKey,
+  buildQueryKey,
+  createRequestEnvelope,
+  validateRequestEnvelope,
+  createHydrationEnvelope,
+  validateHydrationEnvelope,
+  createInvalidationEvent,
+  shouldApplyInvalidation,
+} from '@modern-js/plugin-bff/data-platform';
+```
+
+## Effect runtime validation
+
+Enable strict server-side envelope validation in `modern.config.ts`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      dataPlatform: {
+        requireEnvelope: true,
+        expectedNamespace: 'my-app',
+        selection: {
+          maxDepth: 6,
+          maxFields: 200,
+        },
+      },
+    },
+  },
+});
+```
+
+Envelope validation is enabled by default but does not require an envelope unless `requireEnvelope` is set. Origin validation is enabled by default; set `validateOrigin: false` to skip comparing the envelope origin against the incoming `Origin` header, or the request URL origin when the header is absent.
+
+## Generated API client behavior
+
+When using the generated API client (`@api/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.
+
+The generated client is loader-materialized. Import it from `@api/index` in browser or client-bundled code; direct imports of the server entry (`api/index`) expose the Effect API definition and only provide a placeholder `client`.
+
+The envelope includes:
+
+- operation metadata
+- scoped cache identity
+- request mode
+- selection plan hash
+- optional trace context
+
+For browser cross-origin requests, envelope headers are skipped by default to avoid unintended CORS preflight breakage in cross-project/micro-frontend setups.
+
+If you need envelope headers across origins, set `request.dataPlatform.allowCrossOriginEnvelope = true` and configure CORS to allow the envelope header.
+
+## Network batching
+
+Effect generated clients include micro-batching for GET requests by default. Requests in the same short window are merged into one POST call to `/_data/batch` (under your BFF prefix), while preserving per-item response semantics.
+
+Batching behavior:
+
+- GET-only by default (`allowedMethods` can be adjusted).
+- In-flight dedupe for identical requests.
+- Automatic fallback to single requests when batch endpoint is unavailable.
+- Per-item isolation: one item failure does not fail sibling items.
+- Trace continuity: batch gateway forwards `traceparent` from item headers or envelope metadata.
+
+Server controls are configured in `bff.effect.dataPlatform.batch`:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      dataPlatform: {
+        batch: {
+          endpoint: '/_data/batch',
+          maxBatchSize: 16,
+          maxBatchBytes: 64 * 1024,
+          flushIntervalMs: 8,
+          maxConcurrency: 4,
+          requestTimeoutMs: 10000,
+          allowedMethods: ['GET'],
+        },
+      },
+    },
+  },
+});
+```
+
+## Recommended policy
+
+- Keep `validateOrigin` enabled.
+- Use `expectedNamespace` for each deployed app/remote.
+- Enable `requireEnvelope` in production once all clients are migrated.
+- Keep batching GET-only unless you have strong mutation ordering guarantees.
+- Keep host/remote batch endpoints on each origin; do not route all MF traffic to a single shared batch origin.
+- Use explicit `targetNamespaces` and opt-in subscribers for cross-app invalidation.

package/docs/guides/advanced-features/bff/extend-server.md

@@ -0,0 +1,120 @@
+# Extend BFF Server
+
+In some applications, developers may want to handle all BFF functions uniformly, such as authentication, logging, data processing, etc.
+
+Modern.js allows users to freely extend the BFF Server through [Middleware](/guides/advanced-features/web-server.md#middleware) method.
+
+## Using Middleware
+
+:::tip Version Consistency
+Before using middleware, you need to install the `@modern-js/server-runtime` dependency. Make sure the version of `@modern-js/server-runtime` matches the version of `@modern-js/app-tools` in your project. All Modern.js official packages are released with a uniform version number, and version mismatches may cause compatibility issues.
+
+Check the version of `@modern-js/app-tools` first, then install the same version of `@modern-js/server-runtime`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/server-runtime
+pnpm add @modern-js/server-runtime@<version>
+```
+
+:::
+
+Developers can use middleware by configuring middlewares in `server/modern.server.ts`. The following describes how to write a BFF middleware manually to add permission verification:
+
+```ts title="server/modern.server.ts"
+import {
+  type MiddlewareHandler,
+  defineServerConfig,
+  getCookie,
+} from '@modern-js/server-runtime';
+
+const requireAuthForApi: MiddlewareHandler = async (c, next) => {
+  if (c.req.path.startsWith('/api') && c.req.path !== '/api/login') {
+    const sid = getCookie(c, 'sid');
+    if (!sid) {
+      return c.json({ code: -1, message: 'need login' }, 400);
+    }
+  }
+  await next();
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'require-auth-for-api',
+      handler: requireAuthForApi,
+    },
+  ],
+});
+```
+
+Then add a regular BFF function `api/lambda/hello.ts`:
+
+```ts title="api/lambda/hello.ts"
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
+
+Next, in the frontend `src/routes/page.tsx`, add the interface access code and directly use the integrated method to call:
+
+```ts title="src/routes/page.tsx"
+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>;
+};
+```
+
+Now run the `dev` command to start the project, and access `http://localhost:8080/` to find that the request for `/api/hello` has been intercepted:
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
+
+Finally, modify the frontend code `src/routes/page.tsx`, and call the login interface before accessing `/api/hello`:
+
+:::note
+This part does not implement a real login interface; the code is just for demonstration.
+:::
+
+```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 the access to `/api/hello` is successful:
+
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
+
+The above code simulates defining middleware in `server/Modern.server.ts` and implements a simple login function. Similarly, other functionalities can be implemented in this configuration file to extend the BFF Server.