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

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.md

@@ -0,0 +1,318 @@
+# Basic Usage
+
+In a Modern.js application, developers can define API files under the `api/lambda` directory and export API functions from these files. In the frontend code, these API functions can be directly invoked by importing the file, which initiates the API requests.
+
+:::warning
+`api/lambda/**` is the Hono/file-function compatibility runtime. New UltraModern generated API work should use the strict Effect runtime with `api/index.ts`, `shared/api.ts`, `defineEffectBff(...)`, and Effect `HttpApi` schemas instead.
+:::
+
+This invocation method is called **unified invocation**, where developers do not need to write glue code for the frontend and backend separately, thereby ensuring type safety across both.
+
+## Enable BFF
+
+To enable BFF functionality in a Modern.js project, follow these steps to modify the code:
+
+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
+
+Functions that allow unified invocation are called **BFF Functions**. Here is an example of the simplest BFF function. First, create the `api/lambda/hello.ts` file:
+
+```ts title="api/lambda/hello.ts"
+export const get = async () => 'Hello Modern.js';
+```
+
+Then, import and invoke the function directly in `src/routes/page.tsx`:
+
+```tsx title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    hello().then(setText);
+  }, []);
+  return <div>{text}</div>;
+};
+```
+
+The function imported in `src/routes/page.tsx` will be automatically converted into an API call, eliminating the need to use an SDK or Web Fetch to call the API.
+
+After running `pnpm run dev`, open `http://localhost:8080/` and you can see that the page displays the content returned by the BFF function. In the Network tab, you can see a request was made to `http://localhost:8080/api/hello`.
+
+![Network](https://p6-piu.byteimg.com/tos-cn-i-8jisjyls3a/fd41750f8d414179a9b4ecb519919b36~tplv-8jisjyls3a-3:0:0:q75.png)
+
+## Function Routes
+
+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.md).
+:::
+
+### Default Routes
+
+Files named `index.ts` will be mapped to the parent directory.
+
+- `api/lambda/index.ts` -> `{prefix}/`
+- `api/lambda/user/index.ts` -> `{prefix}/user`
+
+### Nested Routes
+
+Nested directories are supported, and files will be automatically parsed into routes in the same way.
+
+- `api/lambda/hello.ts` -> `{prefix}/hello`
+- `api/lambda/user/list.ts` -> `{prefix}/user/list`
+
+### 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.md#dynamic-path).
+
+- `api/lambda/user/[username]/info.ts` -> `{prefix}/user/:username/info`
+- `api/lambda/user/username/[action].ts` -> `{prefix}/user/username/:action`
+
+### Whitelist
+
+By default, all files under the `api/lambda/` directory are parsed as BFF function files, but the following files are ignored:
+
+- Files starting with an underscore `_`. For example: `_utils.ts`.
+- Files under directories starting with an underscore `_`. For example: `_utils/index.ts`, `_utils/cp.ts`.
+- Test files. For example: `foo.test.ts`.
+- TypeScript type files. For example: `hello.d.ts`.
+- Files under `node_modules`.
+
+## RESTful API
+
+Modern.js BFF functions need to follow RESTful API standards for definition. Developers must define BFF functions according to a set of rules.
+
+:::tip Design Principles
+BFF functions should not only be invoked within the project but also be accessible to other projects via an SDK or Web fetch. Therefore, Modern.js does not define a **private protocol** for unified invocation but uses standard HTTP methods along with common HTTP request parameters like `params`, `query`, and `body` to define functions.
+:::
+
+### Function Export Rules
+
+#### HTTP Method Named Functions
+
+Modern.js BFF functions' export names determine the HTTP method for the corresponding API, such as `get`, `post`, etc. For example, to export a GET API:
+
+```ts
+export const get = async () => {
+  return {
+    name: 'Modern.js',
+    desc: 'A modern web engineering solution',
+  };
+};
+```
+
+The following example exports a `POST` API:
+
+```ts
+export const post = async () => {
+  return {
+    name: 'Modern.js',
+    desc: 'A modern web engineering solution',
+  };
+};
+```
+
+- Modern.js supports 9 HTTP methods: `GET`, `POST`, `PUT`, `DELETE`, `CONNECT`, `TRACE`, `PATCH`, `OPTIONS`, and `HEAD`, which can be used as function export names.
+
+- Names are case-insensitive. If the method is `GET`, it can be written as `get`, `Get`, `GEt`, or `GET`, and the default export, i.e., `export default xxx`, will be mapped to `Get`.
+
+#### Using Async Functions
+
+Modern.js recommends defining BFF functions as async functions, even if there is no asynchronous process in the function, for example:
+
+```ts
+export const get = async () => {
+  return {
+    name: 'Modern.js',
+    desc: 'A modern web engineering solution',
+  };
+};
+```
+
+This is because, during frontend invocation, the BFF function will be automatically converted into an HTTP API call, and HTTP API calls are asynchronous. On the frontend, it is typically used like this:
+
+```tsx title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    hello().then(setText);
+  }, []);
+  return <div>{text}</div>;
+};
+```
+
+Therefore, to keep the type definitions consistent with the actual invocation experience, we recommend defining BFF functions as async functions.
+
+### Function Parameter Rules
+
+Function parameter rules are divided into two parts: dynamic routes in the request path (`Dynamic Path`) and request options (`RequestOption`).
+
+#### Dynamic Path
+
+Dynamic routes will be the first part of the BFF function parameters, with each parameter corresponding to a segment of the dynamic route. For example, the `level` and `id` parameters will be passed to the function in the following example:
+
+```ts title="api/lambda/[level]/[id].ts"
+export default async (level: number, id: number) => {
+  const userData = await queryUser(level, uid);
+  return userData;
+};
+```
+
+Invoke the function by directly passing in the dynamic parameters:
+
+```tsx title="src/routes/page.tsx"
+import { useState, useEffect } from 'react';
+import { get as getUser } from '@api/[level]/[id]';
+
+export default () => {
+  const [name, setName] = useState('');
+
+  useEffect(() => {
+    getUser(6, 001).then(userData => setName(userData.name));
+  }, []);
+
+  return <div>{name}</div>;
+};
+```
+
+#### RequestOption
+
+Parameters following the dynamic path are an object called `RequestOption`, which includes the query string and request body. This field is used to define the types for `data` and `query`.
+
+In a standard function without dynamic routes, `RequestOption` can be obtained from the first parameter, for example:
+
+```ts title="api/lambda/hello.ts"
+import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+
+export async function post({
+  query,
+  data,
+}: RequestOption<Record<string, string>, Record<string, string>>) {
+  // do something
+}
+```
+
+Custom types can also be used here:
+
+```ts title="api/lambda/hello.ts"
+import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+
+type IQuery = {
+  // some types
+};
+type IData = {
+  // some types
+};
+
+export async function post({ query, data }: { query: IQuery; data: IData }) {
+  // do something
+}
+```
+
+When the function file uses dynamic routing, dynamic routes will precede the `RequestOption` object parameter.
+
+```ts title="api/lambda/[sku]/[id]/item.ts"
+export async function post(
+  sku: string,
+  id: string,
+  {
+    data,
+    query,
+  }: RequestOption<Record<string, string>, Record<string, string>>,
+) {
+  // do somethings
+}
+```
+
+Pass the corresponding parameters when invoking the function according to its definition:
+
+```ts title="src/routes/page.tsx"
+import { post } from '@api/[sku]/[id]/item';
+
+export default () => {
+  const addSku = () => {
+    post('0001' /* sku */, '1234' /* id */, {
+      query: {
+        /* ... */
+      },
+      data: {
+        /* ... */
+      },
+    });
+  };
+
+  return <div onClick={addSku}>Add SKU</div>;
+};
+```
+
+## 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.
+
+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`](/apis/app/hooks/shared.md) directory can be created at the root of the project for both `src/` and `api/` to use commonly.