@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.99 → 3.8.1-ultramodern.2

package/docs/configure/app/tools/{ts-checker.mdx → ts-checker.md}

@@ -1,9 +1,3 @@
----
-title: tsChecker
----
-
-import { PackageManagerTabs } from '@theme';
-
 # tools.tsChecker
 
 - **Type:** `Object | Function`
@@ -82,7 +76,26 @@ Type checking runs on [TypeScript Go](https://github.com/microsoft/typescript-go
 
 Modern.js prefers the project's stable `typescript` package when it is TypeScript 7 or newer, and falls back to `@typescript/native-preview` for projects still on the preview lane. To pin stable TypeScript 7, install it in your project:
 
-<PackageManagerTabs command="install typescript -D" />
+
+```sh [npm]
+npm install typescript -D
+```
+
+```sh [yarn]
+yarn add typescript -D
+```
+
+```sh [pnpm]
+pnpm add typescript -D
+```
+
+```sh [bun]
+bun add typescript -D
+```
+
+```sh [deno]
+deno add npm:typescript -D
+```
 
 When `tsgo` is enabled, the default `typescript.typescriptPath` resolves to `typescript/package.json` for TypeScript 7 projects. If you manually set `typescript.typescriptPath`, it must be an absolute path to `typescript/package.json` or `@typescript/native-preview/package.json`.
 

package/docs/configure/app/{usage.mdx → usage.md}

@@ -255,7 +255,7 @@ const config: AppUserConfig = {
 
 ## Runtime Configuration
 
-For detailed information on runtime configuration, please refer to the [Introduction to Runtime Configuration](/configure/app/runtime/0-intro.html).
+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.

package/docs/guides/advanced-features/bff/{cross-project.mdx → cross-project.md}

@@ -1,5 +1,3 @@
-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.
@@ -9,6 +7,7 @@ Cross-project invocation consists of **producer** and **consumer** sides. The pr
 
 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`

package/docs/guides/advanced-features/bff/{data-platform.mdx → data-platform.md}

@@ -1,7 +1,3 @@
----
-title: Data Platform
----
-
 # 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.

package/docs/guides/advanced-features/bff/{extend-server.mdx → extend-server.md}

@@ -2,7 +2,7 @@
 
 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.
+Modern.js allows users to freely extend the BFF Server through [Middleware](/guides/advanced-features/web-server.md#middleware) method.
 
 ## Using Middleware
 

package/docs/guides/advanced-features/bff/frameworks.md

@@ -0,0 +1,243 @@
+# Runtime Framework
+
+Modern.js supports two BFF runtime frameworks:
+
+- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/index`.
+- `hono`: use file-convention BFF handlers from `api/lambda/**`.
+
+`effect` and `hono` are strict runtime modes. There is no automatic fallback between them.
+
+::::info
+This page documents generic Modern.js runtime support. Generated UltraModern
+workspaces always use the `effect` runtime with
+`bff.effect.strictEffectApproach: true`. Add or change generated UltraModern
+HTTP API work through `shared/api.ts` and `api/index.ts`; do not add
+Hono/file-convention handlers, raw request parsing, or manual `Response`
+construction inside those workspaces.
+::::
+
+## 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: {
+      entry: './api/index',
+      strictEffectApproach: true,
+      openapi: {
+        path: '/openapi.json',
+      },
+    },
+  },
+});
+```
+
+Define a shared Effect HttpApi contract (for type-safe client + server):
+
+```ts title="shared/api.ts"
+import {
+  HttpApi,
+  HttpApiEndpoint,
+  HttpApiGroup,
+  Schema,
+} from '@modern-js/plugin-bff/effect-client';
+
+export const bffApi = HttpApi.make('MyApi').add(
+  HttpApiGroup.make('hello').add(
+    HttpApiEndpoint.get('ping', '/ping', {
+      success: Schema.String,
+    }),
+  ),
+);
+```
+
+Implement your Effect API entry at `api/index.ts`:
+
+```ts title="api/index.ts"
+import {
+  Schema,
+  Effect,
+  HttpApiBuilder,
+  defineEffectBff,
+  Layer,
+  ServiceMap,
+} from '@modern-js/plugin-bff/effect-server';
+import { bffApi } from '../shared/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(bffApi, 'hello', handlers =>
+  handlers.handle('ping', () =>
+    GreetingService.use(service => service.hello()).pipe(
+      Effect.catchTag('GreetingUnavailableError', error =>
+        Effect.succeed(error.message),
+      ),
+    ),
+  ),
+);
+
+const layer = HttpApiBuilder.layer(bffApi).pipe(
+  Layer.provide(group),
+  Layer.provide(GreetingService.layer),
+);
+
+export default defineEffectBff({ api: bffApi, layer });
+```
+
+Call Effect endpoints from browser code via `@api/index`:
+
+```ts title="src/routes/page.tsx"
+import api from '@api/index';
+
+const response = await api.client.hello.ping({});
+```
+
+The `api.client.*` surface is materialized by the BFF loader for `@api/index` imports. Do not import `api/index` directly and expect `client` to run in server code, scripts, or tests; direct entry imports expose the server runtime definition, and `client` is only a typed placeholder there.
+
+### Getting Request Context
+
+Sometimes in BFF functions, it's necessary to obtain the request context to handle more logic. In such cases, you can use `useHonoContext` to get it:
+
+```ts title="api/lambda/hello.ts"
+import { useHonoContext } from '@modern-js/server-runtime';
+
+export const get = async () => {
+  const c = useHonoContext();
+  console.info(`access url: ${c.req.url}`);
+  return 'Hello Modern.js';
+};
+```
+
+:::info
+For more details, refer to [useHonoContext](/apis/app/runtime/bff/use-backend-context.md).
+:::
+
+### Getting Cookies
+
+When getting cookies in BFF functions, you need to get the request context through `useHonoContext`, then use `c.req.header('cookie')` to get the Cookie string and parse it manually:
+
+```ts title="api/lambda/cookies.ts"
+import { Api, Get } from '@modern-js/plugin-bff/hono-server';
+import { useHonoContext } from '@modern-js/server-runtime';
+
+// Helper function to parse Cookie string
+function parseCookies(
+  cookieHeader: string | undefined,
+): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  if (!cookieHeader) return cookies;
+
+  cookieHeader.split(';').forEach(cookie => {
+    const [name, ...rest] = cookie.trim().split('=');
+    if (name) {
+      cookies[name] = rest.join('=');
+    }
+  });
+
+  return cookies;
+}
+
+export const getCookies = Api(Get('/cookies'), async () => {
+  const c = useHonoContext();
+  const cookieHeader = c.req.header('cookie');
+  const cookies = parseCookies(cookieHeader);
+  const token = cookies.token;
+  const sessionId = cookies.sessionId;
+  return {
+    hasToken: !!token,
+    token: token || null,
+    sessionId: sessionId || null,
+  };
+});
+```
+
+:::caution Note
+The `c.req.cookie()` method does not exist in the current version. You need to use `c.req.header('cookie')` to get the Cookie string and parse it manually.
+:::
+
+### Defining BFF Functions
+
+When using Hono as the runtime framework, you can define interfaces through [Api functions](/guides/advanced-features/bff/operators.md):
+
+```ts title="api/lambda/user.ts"
+import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { z } from 'zod';
+
+const QuerySchema = z.object({
+  id: z.string(),
+});
+
+export const getUser = Api(
+  Get('/user'),
+  Query(QuerySchema),
+  async ({ query }) => {
+    return {
+      id: query.id,
+      name: 'Modern.js',
+      email: 'modernjs@bytedance.com',
+    };
+  },
+);
+```
+
+:::info
+For more details about Api functions and operators, refer to [Creating Extensible BFF Functions](/guides/advanced-features/bff/operators.md).
+:::
+
+### Using Middleware
+
+Hono supports a rich middleware ecosystem, and you can use middleware in BFF functions:
+
+```ts title="api/lambda/user.ts"
+import { Api, Get, Middleware } from '@modern-js/plugin-bff/hono-server';
+
+export const getUser = Api(
+  Get('/user'),
+  Middleware(async (c, next) => {
+    // You can access Hono's Context in middleware
+    c.res.headers.set('X-Powered-By', 'Modern.js');
+    await next();
+  }),
+  async () => {
+    return {
+      name: 'Modern.js',
+      email: 'modernjs@bytedance.com',
+    };
+  },
+);
+```
+
+:::info
+For more details about middleware, refer to [Creating Extensible BFF Functions](/guides/advanced-features/bff/operators.md#middleware).
+:::
+
+### More Hono Documentation
+
+For more detailed information about Hono, please refer to the [Hono official documentation](https://hono.dev/).

package/docs/guides/advanced-features/bff/{function.mdx → function.md}

@@ -10,9 +10,62 @@ This invocation method is called **unified invocation**, where developers do not
 
 ## Enable BFF
 
-import EnableBFF from '@site-docs-en/components/enable-bff';
+To enable BFF functionality in a Modern.js project, follow these steps to modify the code:
 
-<EnableBFF />
+1. Install BFF plugin dependencies
+
+If the BFF plugin is not yet installed in your project, install it first:
+
+```bash
+pnpm add @modern-js/plugin-bff
+```
+
+:::tip Version Consistency
+Make sure the version of `@modern-js/plugin-bff` 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/plugin-bff`:
+
+```bash
+# Check the current version of @modern-js/app-tools
+pnpm list @modern-js/app-tools
+
+# Install the same version of @modern-js/plugin-bff
+pnpm add @modern-js/plugin-bff@<version>
+```
+
+:::
+
+2. Configure `modern.config.ts`
+
+Import and add the BFF plugin in the `modern.config.ts` file:
+
+```ts title="modern.config.ts"
+import { defineConfig, appTools } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff';
+
+export default defineConfig({
+  plugins: [appTools(), bffPlugin()],
+});
+```
+
+3. Configure TypeScript alias
+
+To correctly recognize the `@api` alias in TypeScript, it is recommended to add path mapping in `tsconfig.json`:
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "paths": {
+      ..., // other paths,
+      "@api/*": ["./api/lambda/*"]
+    }
+  },
+  "include": [
+    ..., // other include directories
+    "api"  // Add api directory
+  ]
+}
+```
 
 ## BFF Functions
 
@@ -49,7 +102,7 @@ After running `pnpm run dev`, open `http://localhost:8080/` and you can see that
 In Modern.js, the routing system for BFF functions is implemented based on the file system, which is another form of **conventional routing**. Each BFF function in the `api/lambda` directory is mapped to an API route. Here are some routing conventions.
 
 :::info
-All routes generated by BFF functions have a common prefix, which defaults to `/api`. This can be configured using [bff.prefix](/configure/app/bff/prefix).
+All routes generated by BFF functions have a common prefix, which defaults to `/api`. This can be configured using [bff.prefix](/configure/app/bff/prefix.md).
 :::
 
 ### Default Routes
@@ -68,7 +121,7 @@ Nested directories are supported, and files will be automatically parsed into ro
 
 ### Dynamic Routes
 
-Similarly, creating a directory or file with `[xxx]` in the name supports dynamic route parameters. The rules for dynamic route function parameters can be found in [dynamic-path](/guides/advanced-features/bff/function#dynamic-path).
+Similarly, creating a directory or file with `[xxx]` in the name supports dynamic route parameters. The rules for dynamic route function parameters can be found in [dynamic-path](/guides/advanced-features/bff/function.md#dynamic-path).
 
 - `api/lambda/user/[username]/info.ts` -> `{prefix}/user/:username/info`
 - `api/lambda/user/username/[action].ts` -> `{prefix}/user/username/:action`
@@ -256,10 +309,10 @@ export default () => {
 
 ## Extend BFF Function
 
-import ExtendBFF from '@site-docs-en/components/extend-bff-function';
+The standard BFF function writing method may not always meet your needs. For example, complex TS type requirements in business scenarios. Modern.js provides a more powerful BFF function writing method.
 
-<ExtendBFF />
+For more details, please refer to - [Creating Extensible BFF Functions](/guides/advanced-features/bff/operators.md).
 
 ## Code Sharing
 
-Besides the BFF functions in the `api/` directory, which can be referenced in the `src/` directory through an integrated calling method, the `src/` and `api/` directories cannot directly reference each other's code by default. To achieve code sharing, a [`shared`](/en/apis/app/hooks/shared.html) directory can be created at the root of the project for both `src/` and `api/` to use commonly.
+Besides the BFF functions in the `api/` directory, which can be referenced in the `src/` directory through an integrated calling method, the `src/` and `api/` directories cannot directly reference each other's code by default. To achieve code sharing, a [`shared`](/apis/app/hooks/shared.md) directory can be created at the root of the project for both `src/` and `api/` to use commonly.