@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/en/guides/advanced-features/bff/cross-project.mdx

@@ -0,0 +1,110 @@
+import { PackageManagerTabs } from '@theme';
+
+# 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/en/guides/advanced-features/bff/data-platform.mdx

@@ -0,0 +1,118 @@
+---
+title: Data Platform
+---
+
+# Data Platform
+
+Modern.js Effect BFF 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,
+        },
+      },
+    },
+  },
+});
+```
+
+When `validateOrigin` is enabled, Effect runtime validates envelope origin against the incoming `Origin` header (if present), otherwise falls back to request URL origin.
+
+## Generated Effect client behavior
+
+When using the generated Effect client (`@api/effect/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.
+
+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/en/guides/advanced-features/bff/extend-server.mdx

@@ -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.html#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.

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

@@ -0,0 +1,118 @@
+---
+sidebar_position: 3
+title: Runtime Framework
+---
+
+# Runtime Framework
+
+Modern.js supports two BFF runtime frameworks:
+
+- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/effect/index`.
+- `hono`: use file-convention BFF handlers from `api/lambda/**`.
+
+`effect` and `hono` are strict runtime modes. There is no automatic fallback between them.
+
+## Switch to Effect runtime
+
+```ts title="modern.config.ts"
+import { bffPlugin } from '@modern-js/plugin-bff';
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [bffPlugin()],
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      openapi: {
+        path: '/openapi.json',
+      },
+    },
+  },
+});
+```
+
+Define a shared Effect HttpApi contract (for type-safe client + server):
+
+```ts title="shared/effect/api.ts"
+import {
+  HttpApi,
+  HttpApiEndpoint,
+  HttpApiGroup,
+  Schema,
+} from '@modern-js/plugin-bff/effect-client';
+
+export const bffEffectApi = HttpApi.make('MyApi').add(
+  HttpApiGroup.make('hello').add(
+    HttpApiEndpoint.get('ping', '/effect/ping', {
+      success: Schema.String,
+    }),
+  ),
+);
+```
+
+Implement your Effect BFF entry at `api/effect/index.ts`:
+
+```ts title="api/effect/index.ts"
+import {
+  Schema,
+  Effect,
+  HttpApiBuilder,
+  defineEffectBff,
+  Layer,
+  ServiceMap,
+} from '@modern-js/plugin-bff/effect-server';
+import { bffEffectApi } from '../../shared/effect/api';
+
+class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
+  'GreetingUnavailableError',
+  {
+    message: Schema.String,
+  },
+) {}
+
+class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingService', {
+  make: Effect.succeed({
+    hello: Effect.fn('GreetingService.hello')(function* () {
+      if (Date.now() < 0) {
+        return yield* Effect.fail(
+          new GreetingUnavailableError({
+            message: 'Greeting service is unavailable',
+          }),
+        );
+      }
+      return yield* Effect.succeed('pong');
+    }),
+  }),
+}) {
+  static readonly layer = Layer.effect(this, this.make);
+}
+
+const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
+  handlers.handle('ping', () =>
+    GreetingService.use(service => service.hello()).pipe(
+      Effect.catchTag('GreetingUnavailableError', error =>
+        Effect.succeed(error.message),
+      ),
+    ),
+  ),
+);
+
+const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
+  Layer.provide(group),
+  Layer.provide(GreetingService.layer),
+);
+
+export default defineEffectBff({ api: bffEffectApi, layer });
+```
+
+Call Effect endpoints from the browser via `@api/effect/index`:
+
+```ts title="src/routes/page.tsx"
+import effectBff from '@api/effect/index';
+
+const response = await effectBff.client.hello.ping({});
+```
+
+import Hono from '@site-docs-en/components/hono';
+
+<Hono />