@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.100 → 3.5.0-ultramodern.102

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.

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

@@ -1,8 +1,3 @@
----
-sidebar_position: 2
-title: Creating Extensible BFF Functions
----
-
 # Creating Extensible BFF Functions
 
 The previous section showed how to export a simple BFF function in a file. In more complex scenarios, each BFF function may need to do independent type validation, pre-logic, etc.
@@ -31,10 +26,6 @@ A BFF function created by the `Api` function consists of the following parts:
 
 The server can define the input parameters and types of the interface. Based on the types, the server will automatically perform type validation at runtime:
 
-import BFFOperatorCode from '@site-docs/components/bff-operator-code';
-
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Post, Query, Data } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -59,8 +50,6 @@ export const addUser = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 :::caution Note
 When using the `Api` function, ensure that all code logic is placed inside the function. Operations such as `console.log` or using `fs` outside the function are not allowed.
 
@@ -86,8 +75,6 @@ addUser({
 
 As shown in the example below, you can specify the route and HTTP Method through the `Get` function:
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
 
@@ -100,12 +87,8 @@ export const getHello = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 When the route is not specified, the interface route is defined according to the file convention. As shown in the example below, with the function writing method, there is a code path `api/lambda/user.ts`, which will register the corresponding interface `/api/user`.
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
 
@@ -113,10 +96,8 @@ import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
 export const get = Api(Query(UserSchema), async ({ query }) => query);
 ```
 
-</BFFOperatorCode>
-
 :::info
-Modern.js recommends defining interfaces based on file conventions to keep routes clear in the project. For specific rules, see [Function Routes](/guides/advanced-features/bff/function#function-routes).
+Modern.js recommends defining interfaces based on file conventions to keep routes clear in the project. For specific rules, see [Function Routes](/guides/advanced-features/bff/function.md#function-routes).
 
 :::
 
@@ -140,8 +121,6 @@ The following are request-related operators. Operators can be combined, but must
 
 Using the `Query` function, you can define the type of query. After using the `Query` function, the query information can be obtained in the input parameters of the interface processing function, and the `query` field can be added to the input parameters of the frontend request function:
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 // Server-side code
 import { Api, Query } from '@modern-js/plugin-bff/hono-server';
@@ -157,8 +136,6 @@ export const get = Api(Query(UserSchema), async ({ query }) => ({
 }));
 ```
 
-</BFFOperatorCode>
-
 ```typescript title="routes/page.tsx"
 // Frontend code
 get({
@@ -173,8 +150,6 @@ get({
 
 URL query parameters are strings by default. If you need numeric types, you need to use `z.coerce.number()` for type conversion:
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -198,8 +173,6 @@ export const getUser = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 :::caution Note
 URL query parameters are all string types. If you need numeric types, you need to use `z.coerce.number()` for conversion, not `z.number()` directly.
 :::
@@ -213,8 +186,6 @@ If you use the Data function, you must follow the HTTP protocol. When the HTTP M
 
 :::
 
-<BFFOperatorCode>
-
 ```typescript title="api/lambda/user.ts"
 import { Api, Data } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -230,8 +201,6 @@ export const post = Api(Data(DataSchema), async ({ data }) => ({
 }));
 ```
 
-</BFFOperatorCode>
-
 ```typescript title="routes/page.tsx"
 // Frontend code
 post({
@@ -246,8 +215,6 @@ post({
 
 Route parameters can implement dynamic routes and get parameters from the path. You can specify path parameters through `Params<T>(schema: z.ZodType<T>)`
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Get, Params } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -265,14 +232,10 @@ export const queryUser = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ### Request Headers
 
 You can define the request headers required by the interface through the `Headers<T>(schema: z.ZodType<T>)` function and pass the request headers through integrated calls:
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Headers } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -286,8 +249,6 @@ export const queryUser = Api(Headers(headerSchema), async ({ headers }) => ({
 }));
 ```
 
-</BFFOperatorCode>
-
 ## Parameter Validation
 
 As mentioned earlier, when using functions such as `Query` and `Data` to define interfaces, the server will automatically validate the data passed from the frontend based on the schema passed to these functions.
@@ -333,8 +294,6 @@ The `Middleware` operator can be configured multiple times, and the execution or
 
 :::
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Middleware } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -356,8 +315,6 @@ export const get = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ## Data Transformation Pipe
 
 The `Pipe` operator can pass in a function that executes after middleware and validation are completed. It can be used in the following scenarios:
@@ -373,8 +330,6 @@ The `Pipe` operator can be configured multiple times. The execution order of fun
 
 :::
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -401,12 +356,8 @@ export const get = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 Also,
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -436,12 +387,8 @@ export const get = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 If you need to do more custom operations on the response, you can pass a function to the `end` function. The input parameter of the function is Hono's Context (`c`), and you can operate on `c.req` and `c.res`:
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -474,8 +421,6 @@ export const get = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ## Response
 
 The following are response-related operators. Through response operators, you can process responses.
@@ -484,8 +429,6 @@ The following are response-related operators. Through response operators, you ca
 
 You can specify the status code returned by the interface through the `HttpCode(statusCode: number)` function
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/hono-server';
 import { z } from 'zod';
@@ -514,14 +457,10 @@ export const post = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ### Response Headers SetHeaders
 
 Supports setting response headers through the `SetHeaders(headers: Record<string, string>)` function
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/hono-server';
 
@@ -534,14 +473,10 @@ export default Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ### Redirect
 
 Supports redirecting the interface through `Redirect(url: string)`:
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, Get, Redirect } from '@modern-js/plugin-bff/hono-server';
 
@@ -552,13 +487,9 @@ export default Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ## Request Context
 
-As mentioned above, through operators, you can get `query`, `data`, `params`, etc. in the input parameters of the interface processing function. But sometimes we need to get more request context information. At this time, we can get it through [`useHonoContext`](/apis/app/runtime/bff/use-backend-context):
-
-<BFFOperatorCode>
+As mentioned above, through operators, you can get `query`, `data`, `params`, etc. in the input parameters of the interface processing function. But sometimes we need to get more request context information. At this time, we can get it through [`useHonoContext`](/apis/app/runtime/bff/use-backend-context.md):
 
 ```typescript title="api/lambda/user.ts"
 import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
@@ -584,8 +515,6 @@ export const queryUser = Api(
 );
 ```
 
-</BFFOperatorCode>
-
 ## FAQ
 
 ### Can I use TypeScript instead of zod schema
@@ -607,8 +536,6 @@ For specific comparisons of different solutions, you can refer to [Why Use Zod](
 
 In frontend development, some server interfaces (such as some configuration interfaces) have long response times, but actually don't need to be updated for a long time. For such interfaces, we can set HTTP cache to improve page performance:
 
-<BFFOperatorCode>
-
 ```typescript
 import { Api, SetHeaders } from '@modern-js/plugin-bff/hono-server';
 
@@ -625,5 +552,3 @@ export const get = Api(
   },
 );
 ```
-
-</BFFOperatorCode>

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

@@ -1,3 +1,7 @@
+# File Upload
+
+BFF combined with runtime framework provides file upload capabilities, supporting integrated calls and pure function manual calls.
+
 ### BFF Function
 
 First, create the `api/lambda/upload.ts` file:

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

@@ -1,7 +1,3 @@
----
-title: BFF
----
-
 # BFF
 
 BFF (Backends for Frontends) is an architectural pattern primarily used to address issues of data aggregation in front-end and back-end collaboration. Under the BFF architecture, front-end applications do not communicate directly with backend services. Instead, they interact with backend services through a dedicated BFF middleware layer, custom-made for the front end.

package/docs/guides/advanced-features/{build-performance.mdx → build-performance.md}

@@ -1,7 +1,3 @@
----
-sidebar_position: 12
----
-
 # Improve Build Performance
 
 Modern.js optimizes build performance by default, but as the project becomes larger, you may encounter some build performance problems.
@@ -9,7 +5,7 @@ Modern.js optimizes build performance by default, but as the project becomes lar
 This document provides some optional speed-up strategies, developers can choose some of them to improve the build performance.
 
 :::tip 📢 Notice
-The strategies in [Bundle Size Optimization](/guides/advanced-features/page-performance/optimize-bundle) can also be used to improve build performance, so we won't repeat them here.
+The strategies in [Bundle Size Optimization](/guides/advanced-features/page-performance/optimize-bundle.md) can also be used to improve build performance, so we won't repeat them here.
 :::
 
 ## General optimization strategy
@@ -96,7 +92,7 @@ export default {
 
 ### Adjust Browserslist for development
 
-This strategy is similar to ["Adjust Browserslist"](/guides/advanced-features/page-performance/optimize-bundle#adjust-browserslist), the difference is that we can set different browserslist for development and production environment, thereby reducing the compilation overhead in the development environment.
+This strategy is similar to ["Adjust Browserslist"](/guides/advanced-features/page-performance/optimize-bundle.md#adjust-browserslist), the difference is that we can set different browserslist for development and production environment, thereby reducing the compilation overhead in the development environment.
 
 For example, you can add the following config to `package.json`, which means that only the latest browsers are compatible in the development environment, and the actual browsers are compatible in the production environment:
 
@@ -131,4 +127,4 @@ export default {
 };
 ```
 
-See [output.sourceMap](/en/configure/app/output/source-map.html) for details.
+See [output.sourceMap](/configure/app/output/source-map.md) for details.