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

package/docs/community/contributing-guide.md

@@ -0,0 +1,252 @@
+# Contributing Guide
+
+Thanks for that you are interested in contributing to Modern.js. Before starting your contribution, please take a moment to read the following guidelines.
+
+## Setup the Dev Environment
+
+### Fork the Repo
+
+[Fork](https://help.github.com/articles/fork-a-repo/) this repository to your
+own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local.
+
+### Install Node.js
+
+We recommend using Node.js 22. You can check your currently used Node.js version with the following command:
+
+```bash
+node -v
+```
+
+If you do not have Node.js installed in your current environment, you can use [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm) to install it.
+
+Here is an example of how to install the Node.js 22 LTS version via nvm:
+
+```bash
+# Install the LTS version of Node.js 22
+nvm install 22 --lts
+
+# Make the newly installed Node.js 22 as the default version
+nvm alias default 22
+
+# Switch to the newly installed Node.js 22
+nvm use 22
+```
+
+### Install pnpm
+
+```sh
+mise install
+```
+
+### Install Dependencies
+
+```sh
+pnpm install
+```
+
+What this will do:
+
+- Install all dependencies
+- Create symlinks between packages in the monorepo
+- Run the `prepare` script to build all packages (this will take some time, but is necessary to make ensure all packages are built)
+
+> A full rebuild of all packages is generally not required after this. If a new feature you are developing requires an updated version of another package, it is usually sufficient to build the changed dependencies.
+
+### Set Git Email
+
+Please make sure you have your email set up in `<https://github.com/settings/emails>`. This will be needed later when you want to submit a pull request.
+
+Check that your git client is already configured the email:
+
+```sh
+git config --list | grep email
+```
+
+Set the email to global config:
+
+```sh
+git config --global user.email "SOME_EMAIL@example.com"
+```
+
+Set the email for local repo:
+
+```sh
+git config user.email "SOME_EMAIL@example.com"
+```
+
+## Making Changes and Building
+
+Once you have set up the local development environment in your forked repo, we can start development.
+
+### Checkout A New Branch
+
+It is recommended to develop on a new branch, as it will make things easier later when you submit a pull request:
+
+```sh
+git checkout -b MY_BRANCH_NAME
+```
+
+### Build the Package
+
+To build the package you want to change, first open the package directory, then run the `build` command:
+
+```sh
+# Replace some-path with the path of the package you want to work on
+cd ./packages/some-path
+pnpm run build
+```
+
+Alternatively, you can build the package from the root directory of the repository using the `--filter` option:
+
+```sh
+pnpm run --filter @modern-js/some-package build
+```
+
+Build all packages:
+
+```sh
+pnpm run prepare
+```
+
+If you need to clean all `node_modules/*` in the project, run the `reset` command:
+
+```sh
+pnpm run reset
+```
+
+## Testing
+
+### Add New Tests
+
+If you've fixed a bug or added code that should be tested, then add some tests.
+
+Modern.js uses [Rstest](https://rstest.rs/) for unit tests across the repository. You can add test cases in the `<PACKAGE_DIR>/tests` folder, using Rstest syntax.
+
+### Run Unit Tests
+
+Before submitting a pull request, it's important to make sure that the changes haven't introduced any regressions or bugs. You can run the unit tests for the project by executing the following command:
+
+```sh
+pnpm run test
+```
+
+Alternatively, you can run the unit tests of single package using the `--filter` option:
+
+```sh
+pnpm run --filter @modern-js/some-package test
+```
+
+### Run E2E Tests
+
+In addition to the unit tests, the Modern.js also includes end-to-end (E2E) tests, which checks the functionality of the application as a whole.
+
+You can run the `test:e2e` command to run the E2E tests:
+
+```sh
+pnpm run test:e2e
+```
+
+If you need to run a specified test, you can add keywords to filter:
+
+```sh
+# Only run test cases with the copy-assets keyword
+npx rstest copy-assets
+```
+
+## Linting
+
+To help maintain consistency and readability of the codebase, we use a ESLint to lint the codes.
+
+You can run the Linter by executing the following command:
+
+```sh
+pnpm run lint
+```
+
+## Benchmarking
+
+You can input `!bench-framework` or `!bench-module` in the comment area of ​​the PR to do benchmarking on `@modern-js/app-tools` and `@modern-js/module-tools` respectively (you need to have Collaborator and above permissions).
+
+You can focus on metrics related to build time and bundle size based on the comparison table output by comments to assist you in making relevant performance judgments and decisions.
+
+Dependencies installation-related metrics base on publishing process, so the data is relatively lagging and is for reference only.
+
+## Documentation
+
+Currently Modern.js provides documentation in English and Chinese. If you can use Chinese, please update both documents at the same time. Otherwise, just update the English documentation.
+
+You can find all the documentation in the `packages/document` folder:
+
+```bash
+root
+└─ packages
+   └─ document  # Documentation for Modern.js Framework
+```
+
+This website is built with Rspress, the document content can be written using markdown or mdx syntax. You can refer to the [Rspress Website](https://rspress.rs/) for detailed usage.
+
+The source code of Rspress can be found in [this repo](https://github.com/web-infra-dev/rspress).
+
+## Submitting Changes
+
+### Add a Changeset
+
+Modern.js is using [Changesets](https://github.com/changesets/changesets) to manage the versioning and changelogs.
+
+If you've changed some packages, you need add a new changeset for the changes. Please run `change` command to select the changed packages and add the changeset info.
+
+```sh
+pnpm run change
+```
+
+### Committing your Changes
+
+Commit your changes to your forked repo, and [create a pull request](https://help.github.com/articles/creating-a-pull-request/).
+
+### Format of PR titles
+
+The format of PR titles follow Conventional Commits.
+
+An example:
+
+```
+feat(plugin-swc): Add `xxx` config
+^    ^    ^
+|    |    |__ Subject
+|    |_______ Scope
+|____________ Type
+```
+
+## Publishing
+
+We use **Modern.js Monorepo Solution** to manage version and changelog.
+
+Repository maintainers can publish a new version of all packages to npm.
+
+Here are the steps to publish (we generally use CI for releases and avoid publishing npm packages locally):
+
+1. Pull latest code from the `main` branch.
+2. Install:
+
+```sh
+pnpm i
+```
+
+3. Build packages:
+
+```sh
+pnpm run prepare
+```
+
+4. Bump version:
+
+```sh
+pnpm run bump
+```
+
+5. Commit the version change.
+
+```sh
+git add .
+git commit -m "Release va.b.c"
+```

package/docs/community/releases.md

@@ -0,0 +1,23 @@
+# Releases
+
+## Changelog
+
+Please visit [GitHub - Releases](https://github.com/web-infra-dev/modern.js/releases) to see what has changed with each release of Modern.js.
+
+## Version Specification
+
+Modern.js follows the [Semantic Versioning](https://semver.org) specification.
+
+- Major version: Contains incompatible API changes.
+- Minor version: Contains backward compatible functional changes.
+- Patch version: Contains backwards compatible bug fixes
+
+## Release Cycle
+
+- Modern.js generally releases an official release every Thursday.
+- If critical bugs appear, we will release a revised version on the same day.
+- We expect to keep Modern.js v2 stable and compatible, there are currently no plans to release the next major version.
+
+## Version Upgrade
+
+Modern.js 3.0 no longer ships the `modern upgrade` command. When you need to upgrade a project, follow the manual migration steps in [Upgrade](/guides/get-started/upgrade.md).

package/docs/community/showcase.md

@@ -0,0 +1,24 @@
+# Showcase
+
+Welcome to the Modern.js showcase page! Here, we present a collection of websites that have been built using Modern.js.
+
+If you have built a website using Modern.js, we would love for you to share it with the community. Simply reply to the GitHub discussion thread with a link to your website. We will collect content on a regular basis and display it on the current page.
+
+## The Cases
+
+
+[![](/img/features/framework.svg)UltraModern.jsFramework
+
+bleedingdev.github.io](https://bleedingdev.github.io/ultramodern.js/)[![](/img/features/api.svg)EffectFramework
+
+effect.website](https://effect.website/)[![](/img/features/url.svg)TanStack RouterFramework
+
+tanstack.com](https://tanstack.com/router)[![](/img/features/compiler.svg)RspackBuilder
+
+rspack.rs](https://rspack.rs/)[![](/img/features/visual.svg)RspressDoc
+
+rspress.rs](https://rspress.rs/)[![](/img/features/app.svg)Modern.jsDoc
+
+modernjs.dev](https://modernjs.dev/en/)[![](/img/features/frameworks.svg)Module FederationModule
+
+module-federation.io](https://module-federation.io/)

package/docs/community/team.md

@@ -0,0 +1,14 @@
+# Meet the Team
+
+The development of Modern.js is driven by ByteDance's Modern.js team and community contributors.
+
+## Core Team Members
+
+The Modern.js core team members:
+
+
+## All Contributors
+
+Thanks to the following friends for their contributions to Modern.js:
+
+[![contributors](https://opencollective.com/modernjs/contributors.svg?width=890&button=false)](https://github.com/web-infra-dev/modern.js/graphs/contributors)

package/docs/configure/app/bff/cross-project.md

@@ -0,0 +1,20 @@
+# bff.crossProject
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+:::tip
+Please refer to the [Enable BFF](/guides/advanced-features/bff/function.md#enable-bff) section in Basic Usage to enable BFF functionality first.
+:::
+
+This configuration is used to enable BFF cross-project invocation functionality. When enabled, the current project can be used as a BFF producer, generating an SDK that can be directly called by other projects.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  },
+});
+```
+
+For detailed configuration and usage of BFF cross-project invocation, please refer to the [BFF Cross-Project Invocation Guide](/guides/advanced-features/bff/cross-project.md).

package/docs/configure/app/bff/effect.md

@@ -0,0 +1,313 @@
+# bff.effect
+
+- **Type:**
+
+```ts
+type BffEffectUserConfig = {
+  entry?: string;
+  strictEffectApproach?: true;
+  openapi?: boolean | { path?: string };
+  dataPlatform?: {
+    enabled?: boolean;
+    requireEnvelope?: boolean;
+    envelopeHeader?: string;
+    expectedNamespace?: string;
+    validateOrigin?: boolean;
+    requireTraceContext?: boolean;
+    selection?: {
+      maxDepth?: number;
+      maxFields?: number;
+      allowedLeafPaths?: string[];
+    };
+    batch?: {
+      enabled?: boolean;
+      endpoint?: `/${string}`;
+      maxBatchSize?: number;
+      maxBatchBytes?: number;
+      flushIntervalMs?: number;
+      maxConcurrency?: number;
+      requestTimeoutMs?: number;
+      allowedMethods?: string[];
+    };
+  };
+};
+```
+
+- **Default:** `{}`
+
+:::tip
+Please refer to the [Enable BFF](/guides/advanced-features/bff/function.md#enable-bff) section in Basic Usage to enable BFF functionality first.
+:::
+
+`bff.effect` is only effective when `bff.runtimeFramework` is set to `'effect'`.
+
+:::caution Install the Effect peers yourself
+`effect` and `@effect/opentelemetry` are **optional exact peer dependencies** of
+`@modern-js/plugin-bff`, not dependencies. The plugin no longer bundles a copy —
+Effect 4 derives `Context` / `Service` keys per module instance, so a bundled copy
+would give your app a second Effect identity. Before setting
+`runtimeFramework: 'effect'` or importing `@modern-js/plugin-bff/effect`,
+`/effect-server`, `/effect-edge` or `/effect-client`, install the exact cohort:
+
+```bash
+pnpm add effect@4.0.0-beta.107 @effect/opentelemetry@4.0.0-beta.107
+```
+
+The pin is exact because UltraModern ships Effect as one lockstep cohort. Apps
+using only `runtimeFramework: 'hono'` or the `./data-platform` lane need neither
+package.
+:::
+
+Generated UltraModern workspaces use this runtime as the only generated HTTP API
+path. The API contract lives at `shared/api.ts`, the server runtime lives at
+`api/index.ts`, clients live under `src/api/*-client.ts`, and generated checks
+reject `api/effect`, `api/lambda`, `shared/effect`, `src/effect`, Hono server
+imports, raw request handlers, manual request parsing, and manual `Response`
+construction in API modules.
+
+For Effect v4, TypeScript should use export-map aware module resolution.
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler"
+  }
+}
+```
+
+## bff.effect.entry
+
+- **Type:** `string`
+- **Default:** `<apiDirectory>/index`
+
+Specifies the entry module for Effect HttpApi runtime.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      entry: './api/index',
+    },
+  },
+});
+```
+
+## bff.effect.strictEffectApproach
+
+- **Type:** `true`
+- **Default:** `true`
+
+Effect BFF modules must expose the strict Effect API surface
+(`defineEffectBff(...)` or `{ api, layer }`) and raw request handlers are
+rejected. Generated UltraModern apps write this marker explicitly and pair it
+with source checks that reject Hono server imports, manual request parsing, and
+manual `Response` construction in generated API modules.
+
+## bff.effect.openapi
+
+- **Type:** `boolean | { path?: string }`
+- **Default:** `false`
+
+Enable OpenAPI endpoint generation for Effect HttpApi runtime.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      openapi: {
+        path: '/openapi.json',
+      },
+    },
+  },
+});
+```
+
+## bff.effect.dataPlatform
+
+- **Type:**
+
+```ts
+{
+  enabled?: boolean;
+  requireEnvelope?: boolean;
+  envelopeHeader?: string;
+  expectedNamespace?: string;
+  validateOrigin?: boolean;
+  requireTraceContext?: boolean;
+  selection?: {
+    maxDepth?: number;
+    maxFields?: number;
+    allowedLeafPaths?: string[];
+  };
+  batch?: {
+    enabled?: boolean;
+    endpoint?: `/${string}`;
+    maxBatchSize?: number;
+    maxBatchBytes?: number;
+    flushIntervalMs?: number;
+    maxConcurrency?: number;
+    requestTimeoutMs?: number;
+    allowedMethods?: string[];
+  };
+}
+```
+
+- **Default:**
+
+```ts
+{
+  enabled: true,
+  requireEnvelope: false,
+  envelopeHeader: 'x-modernjs-data-envelope',
+  validateOrigin: true,
+  requireTraceContext: false,
+  batch: {
+    enabled: true,
+    endpoint: '/_data/batch',
+    maxBatchSize: 16,
+    maxBatchBytes: 64 * 1024,
+    flushIntervalMs: 8,
+    maxConcurrency: 4,
+    requestTimeoutMs: 10000,
+    allowedMethods: ['GET'],
+  },
+}
+```
+
+Configure request-envelope validation for Effect runtime.
+
+Generated Effect client requests batching against `${bff.prefix}${batch.endpoint}` (for example, `/bff-api/_data/batch`).
+
+Envelope validation is enabled by default but optional: requests without an envelope pass unless `requireEnvelope` is `true`. If an envelope is present, runtime validates it against the configured namespace, origin, trace, and selection policy. `expectedNamespace` is unset by default, and `selection` has no default limits unless configured.
+
+Origin validation is enabled by default. Runtime compares envelope origin with request `Origin` header first, then falls back to request URL origin; set `validateOrigin: false` to disable that comparison.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+    effect: {
+      dataPlatform: {
+        requireEnvelope: true,
+        expectedNamespace: 'my-app',
+        selection: {
+          maxDepth: 6,
+          maxFields: 200,
+        },
+      },
+    },
+  },
+});
+```
+
+`batch.flushIntervalMs` controls the client-side micro-batch window in the generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.
+
+The generated `api.client.*` API only exists for loader-materialized `@api/index` imports. Directly importing the server entry (`api/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.
+
+## Effect cohort
+
+UltraModern-generated workspaces pin the framework-compatible Effect cohort
+through `pnpm-workspace.yaml` overrides. For the current UltraModern cohort,
+generated apps use:
+
+```yaml
+trustPolicyExclude:
+  - 'effect@4.0.0-beta.107'
+  - '@effect/opentelemetry@4.0.0-beta.107'
+
+overrides:
+  '@effect/opentelemetry': 4.0.0-beta.107
+  '@effect/vitest': 4.0.0-beta.107
+  effect: 4.0.0-beta.107
+```
+
+Do not add a different direct `effect` version in an app package. A mismatched
+Effect beta can fail while building layers or HTTP middleware because runtime
+services come from different package instances. The strict 24-hour release-age
+gate applies to installed packages; the current cohort has no Effect age
+exemption, and override-only `@effect/vitest` is not an installed approval
+target. `trustPolicyExclude` is a separate policy:
+its exact `effect` and `@effect/opentelemetry` exceptions cover their
+trusted-publisher to provenance metadata transition and are not release-age
+approvals.
+
+## Contract tests
+
+Strict Effect APIs should test the declared `HttpApi` contract, not a raw
+request handler. Edge-compatible tests can use the framework helper:
+
+```ts
+import { createEffectBffTestHandler } from '@modern-js/plugin-bff/effect-edge';
+import apiModule from '../api/index';
+
+const testApi = await createEffectBffTestHandler({
+  module: apiModule,
+  prefix: '/api',
+});
+
+const response = await testApi.handler(new Request('http://localhost/api/ping'));
+```
+
+If you manually compose an Effect web handler in a low-level proof, provide the
+platform services explicitly:
+
+```ts
+import {
+  HttpApiBuilder,
+  HttpRouter,
+  HttpServer,
+  Layer,
+} from '@modern-js/plugin-bff/effect-server';
+
+const handler = HttpRouter.toWebHandler(
+  HttpApiBuilder.layer(api).pipe(
+    Layer.provide(apiGroupLayer),
+    Layer.provide(HttpServer.layerServices),
+  ),
+).handler;
+```
+
+Prefer the generated helper unless the test needs to inspect the low-level
+Effect router composition.
+
+## Dynamic CORS
+
+For dynamic origin predicates, use Effect HTTP middleware as a layer. In the
+current Effect v4 beta cohort, `HttpRouter.middleware(...)` returns a `Layer`
+directly:
+
+```ts
+import {
+  Effect,
+  HttpApiBuilder,
+  HttpMiddleware,
+  HttpRouter,
+  Layer,
+} from '@modern-js/plugin-bff/effect-server';
+
+const corsLayer = HttpRouter.middleware(
+  Effect.succeed(
+    HttpMiddleware.cors({
+      allowedOrigins: origin =>
+        origin.endsWith('.example.com') ? origin : undefined,
+    }),
+  ),
+);
+
+const layer = HttpApiBuilder.layer(api).pipe(
+  Layer.provide(apiGroupLayer),
+  Layer.provide(corsLayer),
+);
+```
+
+Do not read a `.layer` property from `HttpRouter.middleware(...)`.
+
+## Other transports
+
+`strictEffectApproach` governs generated HTTP API modules. Effect RPC,
+WebSockets, and other transports remain valid when they are modeled as explicit
+transport surfaces with typed Effect programs. They do not make raw HTTP
+request handlers valid inside generated UltraModern API modules.

package/docs/configure/app/bff/prefix.md

@@ -0,0 +1,29 @@
+# bff.prefix
+
+- **Type:** `string`
+- **Default:** `/api`
+
+:::tip
+Please refer to the [Enable BFF](/guides/advanced-features/bff/function.md#enable-bff) section in Basic Usage to enable BFF functionality first.
+:::
+
+By default, the prefix for accessing routes in the BFF API directory is `/api`, as shown in the following directory structure:
+
+```bash
+api
+└── hello.ts
+```
+
+The route corresponding to `api/hello.ts` when accessed is `localhost:8080/api/hello`.
+
+This configuration option can modify the default route prefix:
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    prefix: '/api-demo',
+  },
+});
+```
+
+The corresponding route for `api/hello.ts` when accessed is `localhost:8080/api-demo/hello`.

package/docs/configure/app/bff/runtime-framework.md

@@ -0,0 +1,26 @@
+# bff.runtimeFramework
+
+- **Type:** `'hono' | 'effect'`
+- **Default:** `'effect'`
+
+:::tip
+Please refer to the [Enable BFF](/guides/advanced-features/bff/function.md#enable-bff) section in Basic Usage to enable BFF functionality first.
+:::
+
+Controls which runtime framework Modern.js uses for BFF routing.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    runtimeFramework: 'effect',
+  },
+});
+```
+
+- Set to `'effect'` to run BFF only from `api/index` (Effect HttpApi runtime).
+- Set to `'hono'` to run BFF only from file-convention handlers under `api/lambda/**`.
+
+There is no implicit fallback between runtimes. Choose one runtime mode per app.
+Generated UltraModern apps use strict Effect APIs by default and set
+`bff.effect.strictEffectApproach: true`; `hono` and `api/lambda/**` are not
+valid generated UltraModern HTTP API paths.