@bleedingdev/modern-js-main-doc 3.4.0-ultramodern.9 → 3.5.0-ultramodern.1

package/docs/en/community/blog/v3-release-note.mdx

@@ -591,7 +591,7 @@ As Node.js continues to evolve, Node.js 18 has reached EOL. In Modern.js 3.0, we
 
 #### Storybook Rsbuild
 
-In Modern.js 3.0, we implemented Storybook for Modern.js applications based on [Storybook Rsbuild](https://github.com/rspack-contrib/storybook-rsbuild).
+In Modern.js 3.0, we implemented Storybook for Modern.js applications based on [Storybook Rsbuild](https://github.com/rstackjs/storybook-rsbuild).
 
 Through a Storybook Addon, we convert and merge Modern.js configuration into Rsbuild configuration, and use Storybook Rsbuild to drive the build, keeping Storybook debugging aligned with development command configurations.
 

package/docs/en/configure/app/bff/effect.mdx

@@ -9,6 +9,7 @@ title: effect
 ```ts
 type BffEffectUserConfig = {
   entry?: string;
+  strictEffectApproach?: true;
   openapi?: boolean | { path?: string };
   dataPlatform?: {
     enabled?: boolean;
@@ -44,6 +45,13 @@ import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
 
 `bff.effect` is only effective when `bff.runtimeFramework` is set to `'effect'`.
 
+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"
@@ -58,7 +66,7 @@ For Effect v4, TypeScript should use export-map aware module resolution.
 ## bff.effect.entry
 
 - **Type:** `string`
-- **Default:** `<apiDirectory>/effect/index`
+- **Default:** `<apiDirectory>/index`
 
 Specifies the entry module for Effect HttpApi runtime.
 
@@ -67,12 +75,23 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
-      entry: './api/effect/index',
+      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 }`
@@ -173,4 +192,98 @@ export default defineConfig({
 
 `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 `effectBff.client.*` API only exists for loader-materialized `@api/effect/*` imports. Directly importing the server entry (`api/effect/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.
+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 `3.5.0-ultramodern.1`, generated
+apps use:
+
+```yaml
+overrides:
+  '@effect/vitest': 4.0.0-beta.89
+  effect: 4.0.0-beta.89
+```
+
+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.
+
+## 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/en/configure/app/bff/runtime-framework.mdx

@@ -21,8 +21,10 @@ export default defineConfig({
 });
 ```
 
-- Set to `'effect'` to run BFF only from `api/effect/index` (Effect HttpApi runtime).
+- 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 the Effect lane by default; set `runtimeFramework: 'hono'` only for the compatibility runtime.
+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.

package/docs/en/configure/app/experiments/source-build.mdx

@@ -19,7 +19,7 @@ More detail can see ["Source Code Build Mode"](https://modernjs.dev/en/guides/ad
 
 ### Options
 
-`experiments.sourceBuild` is implemented based on [@rsbuild/plugin-source-build](https://github.com/rspack-contrib/rsbuild-plugin-source-build?tab=readme-ov-file#options). You can pass plugin options like this:
+`experiments.sourceBuild` is implemented based on [@rsbuild/plugin-source-build](https://github.com/rstackjs/rsbuild-plugin-source-build?tab=readme-ov-file#options). You can pass plugin options like this:
 
 ```ts
 export default {

package/docs/en/configure/app/html/template-parameters.mdx

@@ -30,7 +30,7 @@ type DefaultParameters = {
 };
 ```
 
-Define the parameters in the HTML template, corresponding to the `templateParameters` config of [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin). You can use the config as an object or a function.
+Define the parameters in the HTML template, corresponding to the `templateParameters` config of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin). You can use the config as an object or a function.
 
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 

package/docs/en/configure/app/output/convert-to-rem.mdx

@@ -80,4 +80,4 @@ export default {
 };
 ```
 
-For detailed usage, please refer to [rsbuild-plugin-rem](https://github.com/rspack-contrib/rsbuild-plugin-rem).
+For detailed usage, please refer to [rsbuild-plugin-rem](https://github.com/rstackjs/rsbuild-plugin-rem).

package/docs/en/configure/app/security/check-syntax.mdx

@@ -70,4 +70,4 @@ If a syntax error is detected, you can handle it in the following ways:
 
 ### Options
 
-`security.checkSyntax` is implemented based on `@rsbuild/plugin-check-syntax`. For specific options, please refer to [@rsbuild/plugin-check-syntax](https://github.com/rspack-contrib/rsbuild-plugin-check-syntax).
+`security.checkSyntax` is implemented based on `@rsbuild/plugin-check-syntax`. For specific options, please refer to [@rsbuild/plugin-check-syntax](https://github.com/rstackjs/rsbuild-plugin-check-syntax).

package/docs/en/configure/app/tools/html-plugin.mdx

@@ -38,7 +38,7 @@ const defaultOptions = {
 SSR Application does not enable the `minify.removeComments` configuration, otherwise the SSR rendering will fail.
 :::
 
-The configs of [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) can be modified through `tools.htmlPlugin`.
+The configs of [html-rspack-plugin](https://github.com/rstackjs/html-rspack-plugin) can be modified through `tools.htmlPlugin`.
 
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 

package/docs/en/configure/app/tools/ts-checker.mdx

@@ -43,7 +43,9 @@ By default, the [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild
 
 ## Example
 
-When the value of `tsChecker` is of type Object, it will be deeply merged with the default configuration.
+### Object Type
+
+When the value of `tsChecker` is an object, it will be deeply merged with the default configuration.
 
 ```ts
 export default {
@@ -57,6 +59,23 @@ export default {
 };
 ```
 
+### Function Type
+
+When the value of `tsChecker` is a function, the default configuration will be passed as the first argument. You can directly modify the configuration object or return an object as the final configuration.
+
+```ts
+export default {
+  tools: {
+    tsChecker(options) {
+      options.async = false;
+      return options;
+    },
+  },
+};
+```
+
+> Please refer to [@rsbuild/plugin-type-check](https://github.com/rstackjs/rsbuild-plugin-type-check) for more details.
+
 ## TypeScript Go by Default
 
 Type checking runs on [TypeScript Go](https://github.com/microsoft/typescript-go) (`tsgo`) by default in this fork. The capability is provided by [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin), which is integrated by [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check), and reduces type-checking time by about 5-10x.

package/docs/en/guides/advanced-features/bff/data-platform.mdx

@@ -4,7 +4,7 @@ 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.
+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.
 
 ## What it solves
 
@@ -57,11 +57,11 @@ export default defineConfig({
 
 Envelope validation is enabled by default but does not require an envelope unless `requireEnvelope` is set. Origin validation is enabled by default; set `validateOrigin: false` to skip comparing the envelope origin against the incoming `Origin` header, or the request URL origin when the header is absent.
 
-## Generated Effect client behavior
+## Generated API 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.
+When using the generated API client (`@api/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.
 
-The generated client is loader-materialized. Import it from `@api/effect/*` in browser or client-bundled code; direct imports of the server entry (`api/effect/index`) expose the Effect BFF definition and only provide a placeholder `client`.
+The generated client is loader-materialized. Import it from `@api/index` in browser or client-bundled code; direct imports of the server entry (`api/index`) expose the Effect API definition and only provide a placeholder `client`.
 
 The envelope includes:
 

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

@@ -7,11 +7,20 @@ title: Runtime Framework
 
 Modern.js supports two BFF runtime frameworks:
 
-- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/effect/index`.
+- `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"
@@ -23,6 +32,8 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
+      entry: './api/index',
+      strictEffectApproach: true,
       openapi: {
         path: '/openapi.json',
       },
@@ -33,7 +44,7 @@ export default defineConfig({
 
 Define a shared Effect HttpApi contract (for type-safe client + server):
 
-```ts title="shared/effect/api.ts"
+```ts title="shared/api.ts"
 import {
   HttpApi,
   HttpApiEndpoint,
@@ -41,18 +52,18 @@ import {
   Schema,
 } from '@modern-js/plugin-bff/effect-client';
 
-export const bffEffectApi = HttpApi.make('MyApi').add(
+export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
-    HttpApiEndpoint.get('ping', '/effect/ping', {
+    HttpApiEndpoint.get('ping', '/ping', {
       success: Schema.String,
     }),
   ),
 );
 ```
 
-Implement your Effect BFF entry at `api/effect/index.ts`:
+Implement your Effect API entry at `api/index.ts`:
 
-```ts title="api/effect/index.ts"
+```ts title="api/index.ts"
 import {
   Schema,
   Effect,
@@ -61,7 +72,7 @@ import {
   Layer,
   ServiceMap,
 } from '@modern-js/plugin-bff/effect-server';
-import { bffEffectApi } from '../../shared/effect/api';
+import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
   'GreetingUnavailableError',
@@ -87,7 +98,7 @@ class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingSer
   static readonly layer = Layer.effect(this, this.make);
 }
 
-const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
+const group = HttpApiBuilder.group(bffApi, 'hello', handlers =>
   handlers.handle('ping', () =>
     GreetingService.use(service => service.hello()).pipe(
       Effect.catchTag('GreetingUnavailableError', error =>
@@ -97,23 +108,23 @@ const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
   ),
 );
 
-const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
+const layer = HttpApiBuilder.layer(bffApi).pipe(
   Layer.provide(group),
   Layer.provide(GreetingService.layer),
 );
 
-export default defineEffectBff({ api: bffEffectApi, layer });
+export default defineEffectBff({ api: bffApi, layer });
 ```
 
-Call Effect endpoints from browser code via `@api/effect/index`:
+Call Effect endpoints from browser code via `@api/index`:
 
 ```ts title="src/routes/page.tsx"
-import effectBff from '@api/effect/index';
+import api from '@api/index';
 
-const response = await effectBff.client.hello.ping({});
+const response = await api.client.hello.ping({});
 ```
 
-The `effectBff.client.*` surface is materialized by the BFF loader for `@api/effect/*` imports. Do not import `api/effect/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.
+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.
 
 import Hono from '@site-docs-en/components/hono';
 

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

@@ -2,6 +2,10 @@
 
 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

package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -92,7 +92,7 @@ export default {
 };
 ```
 
-See details in [plugin-image-compress](https://github.com/rspack-contrib/rsbuild-plugin-image-compress).
+See details in [plugin-image-compress](https://github.com/rstackjs/rsbuild-plugin-image-compress).
 
 ## Split Chunk
 

package/docs/en/guides/basic-features/debug/using-storybook.mdx

@@ -97,4 +97,4 @@ Now you can request the path configured in `bff.prefix`; if not configured, use
 
 ## Example
 
-You can check out the [example](https://github.com/rspack-contrib/storybook-rsbuild/tree/main/sandboxes/modernjs-react) to learn how to use Storybook in Modern.js.
+You can check out the [example](https://github.com/rstackjs/storybook-rsbuild/tree/main/sandboxes/modernjs-react) to learn how to use Storybook in Modern.js.

package/docs/en/guides/basic-features/static-assets/json-files.mdx

@@ -38,7 +38,7 @@ import { name } from './example.json';
 
 YAML is a data serialization language commonly used for writing configuration files.
 
-You can configure the [YAML plugin](https://github.com/rspack-contrib/rsbuild-plugin-yaml) in `modern.config.ts` to support importing `.yaml` or `.yml` files, they will be automatically converted to JSON format.
+You can configure the [YAML plugin](https://github.com/rstackjs/rsbuild-plugin-yaml) in `modern.config.ts` to support importing `.yaml` or `.yml` files, they will be automatically converted to JSON format.
 
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
@@ -85,7 +85,7 @@ declare module '*.yml' {
 
 Toml is a semantically explicit, easy-to-read configuration file format.
 
-You can configure the [TOML plugin](https://github.com/rspack-contrib/rsbuild-plugin-toml) in `modern.config.ts` to support importing `.toml` files, it will be automatically converted to JSON format.
+You can configure the [TOML plugin](https://github.com/rstackjs/rsbuild-plugin-toml) in `modern.config.ts` to support importing `.toml` files, it will be automatically converted to JSON format.
 
 ```ts
 import { defineConfig } from '@modern-js/app-tools';

package/docs/en/guides/get-started/_meta.json

@@ -4,5 +4,6 @@
   "quick-start",
   "upgrade",
   "glossary",
-  "tech-stack"
+  "tech-stack",
+  "ai-coding-agents"
 ]

package/docs/en/guides/get-started/ai-coding-agents.mdx

@@ -0,0 +1,48 @@
+---
+title: AI Tools
+sidebar_position: 6
+---
+
+# Modern.js For AI
+
+Modern.js provides a toolkit for AI agents that helps developers use AI to efficiently complete feature development, dependency upgrades, and version migration for Modern.js applications.
+
+## llms.txt
+
+Modern.js docs follow the [llms.txt specification](https://llmstxt.org/), auto-generated by [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms), accessible via `/llms.txt` or `/llms-full.txt`:
+
+- Index: [`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
+- Full text: `https://modernjs.dev/llms-full.txt` (large — fetch on demand)
+
+Most "what is this API / config" questions can be answered from llms.txt. Just let your agent retrieve it on demand; no need to copy docs into your project.
+
+## Skills
+
+Skills are on-demand AI capabilities following the [Agent Skills open standard](https://github.com/vercel-labs/skills). User-facing Skills:
+
+| Skill | Identifier | Description |
+|---|---|---|
+| Upgrade to v3 | `modernjs-migrate-to-v3` | Migrate a v2 app to v3: safe rewrites + manual checklist + migration report |
+| Enable features | `modernjs-feature-enable` | Enable BFF / SSG / styled-components for v3 apps, and scaffold Tailwind CSS / custom Web Server |
+
+> Skills are not force-installed or implicitly installed — you install them explicitly. RSC and micro-frontend setups are configuration or architecture decisions, not one-click `modernjs-feature-enable` actions.
+
+## Installing Skills
+
+Modern.js user-facing Skills live in the repo's root `skills/` directory and follow the [Agent Skills open standard](https://github.com/vercel-labs/skills). The recommended way is the standard `skills` CLI, installing straight from GitHub:
+
+```bash
+# List installable Skills
+npx skills add web-infra-dev/modern.js --list
+
+# Install a single Skill into your agent directory (--agent: claude-code / codex / cursor / ...)
+npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
+```
+
+It installs the entire Skill directory (`SKILL.md` + `scripts/` + `references/`) into the corresponding agent directory, ready to trigger there.
+
+> To pin a specific version, append `#<ref>` (a tag, branch, or commit) to the repo — it installs the Skill as of that ref (replace `<tag>` with a release tag that contains this Skill):
+>
+> ```bash
+> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
+> ```