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

package/docs/plugin/server-plugins/api.md

@@ -0,0 +1,209 @@
+# Plugin API
+
+Modern.js's Server plugins allow you to extend and customize functionality during the server-side request processing phase, such as adding middleware, modifying request responses, etc.
+
+:::info
+
+Server plugins need to be configured via the `plugins` field in `server/modern.server.ts`.
+
+:::
+
+## Plugin Basic Structure
+
+A typical Server plugin structure is as follows:
+
+```typescript
+import type { ServerPlugin } from '@modern-js/server-runtime';
+
+const myServerPlugin = (): ServerPlugin => ({
+  name: '@my-org/my-server-plugin', // Plugin name, ensure uniqueness
+  setup: api => {
+    // Use the API here to register hooks, add middleware, etc.
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+      middlewares?.push({
+        name: 'my-middleware',
+        handler: async (c, next) => {
+          console.log('Processing request...');
+          await next();
+        },
+      });
+    });
+  },
+});
+
+export default myServerPlugin;
+```
+
+- `name`: A unique identifier for the plugin.
+- The `setup` function receives an `api` object, which provides all available Server plugin APIs.
+
+## Information Retrieval
+
+#### `api.getServerContext`
+
+Gets the context information of the Modern.js server.
+
+- **Returns:** A `ServerContext` object containing the following fields:
+
+| Field Name          | Type              | Description                            |
+| ------------------- | ----------------- | -------------------------------------- |
+| `middlewares`       | `MiddlewareObj[]` | Middleware list                        |
+| `renderMiddlewares` | `MiddlewareObj[]` | Render middleware list                 |
+| `routes`            | `ServerRoute[]`   | Server routing information             |
+| `appDirectory`      | `string`          | Absolute path to the project root      |
+| `apiDirectory`      | `string`          | Absolute path to the API module dir    |
+| `lambdaDirectory`   | `string`          | Absolute path to the Lambda module dir |
+| `sharedDirectory`   | `string`          | Absolute path to the shared module dir |
+| `distDirectory`     | `string`          | Absolute path to the output directory  |
+| `plugins`           | `ServerPlugin[]`  | List of currently registered plugins   |
+
+- **Example:**
+
+```typescript
+api.onPrepare(() => {
+  const serverContext = api.getServerContext();
+  console.log(`App directory: ${serverContext.appDirectory}`);
+  console.log(`${serverContext.plugins.length} plugins registered`);
+});
+```
+
+:::info
+The context information returned by `getServerContext` is read-only. Use `updateServerContext` if you need to modify it.
+:::
+
+***
+
+#### `api.getServerConfig`
+
+Gets the server configuration defined by the user in the `server/modern.server.ts` file.
+
+- **Returns:** The user-defined server configuration object.
+- **Example:**
+
+```typescript
+api.onPrepare(() => {
+  const serverConfig = api.getServerConfig();
+  if (serverConfig.middlewares) {
+    console.log('User has customized middleware configuration');
+  }
+});
+```
+
+***
+
+#### `api.getHooks`
+
+Gets all registered hook functions.
+
+- **Returns:** An object containing all hook functions.
+- **Example:**
+
+```typescript
+const hooks = api.getHooks();
+// Manually trigger the onPrepare hook
+await hooks.onPrepare.call();
+```
+
+:::warning
+In custom plugins, you can only manually call the hooks registered by the corresponding plugin and cannot call official hooks to avoid affecting the normal execution order of the application.
+:::
+
+***
+
+## Context Modification
+
+#### `api.updateServerContext`
+
+Updates the server context information.
+
+- **Type:** `api.updateServerContext(updateContext: DeepPartial<ServerContext>)`
+- **Parameters:**
+  - `updateContext`: The context object to update (partial update).
+- **Execution Phase:** Can be used at any stage.
+- **Example:**
+
+```typescript
+api.onPrepare(() => {
+  const context = api.getServerContext();
+  api.updateServerContext({
+    middlewares: [
+      ...context.middlewares,
+      {
+        name: 'new-middleware',
+        handler: async (c, next) => {
+          await next();
+        },
+      },
+    ],
+  });
+});
+```
+
+***
+
+## Lifecycle Hooks
+
+#### `api.onPrepare`
+
+Adds additional logic during the server preparation phase.
+
+- **Type:** `api.onPrepare(prepareFn: () => void | Promise<void>)`
+- **Parameters:**
+  - `prepareFn`: A preparation function, without parameters, can be asynchronous.
+- **Execution Phase:** After the server completes configuration validation and before applying middleware.
+- **Example:**
+
+```typescript
+api.onPrepare(async () => {
+  const { middlewares } = api.getServerContext();
+
+  // Add custom middleware
+  middlewares.push({
+    name: 'request-logger',
+    handler: async (c, next) => {
+      const start = Date.now();
+      await next();
+      const duration = Date.now() - start;
+      console.log(`Request duration: ${duration}ms`);
+    },
+  });
+});
+```
+
+:::info
+In the `onPrepare` hook, you can modify the context object returned by `getServerContext()` (such as `middlewares`, `renderMiddlewares`), and these modifications will take effect when the server starts.
+:::
+
+***
+
+#### `api.onReset`
+
+Adds additional logic when the server resets.
+
+- **Type:** `api.onReset(resetFn: (params: { event: ResetEvent }) => void | Promise<void>)`
+- **Parameters:**
+  - `resetFn`: A reset handler function that receives reset event parameters.
+    - `event.type`: Event type, possible values:
+      - `'repack'`: Repack event
+      - `'file-change'`: File change event
+    - `event.payload`: When `type` is `'file-change'`, contains an array of file change information.
+- **Execution Phase:** When files change or repack is needed.
+- **Example:**
+
+```typescript
+api.onReset(async ({ event }) => {
+  if (event.type === 'file-change') {
+    console.log('File changes detected:', event.payload);
+    // Perform cleanup or re-initialization operations
+  } else if (event.type === 'repack') {
+  }
+});
+```
+
+***
+
+## Other Notes
+
+- Refer to [Server Plugin Lifecycle](/plugin/server-plugins/life-cycle.md) to understand the execution order of plugin hooks.
+- The execution order of middleware can be controlled through the `order` field (`'pre'`, `'default'`, `'post'`), or through the `before` field to specify execution before other middleware.

package/docs/plugin/server-plugins/life-cycle.md

@@ -0,0 +1,13 @@
+# Life Cycle
+
+
+:::info
+
+**Runtime Hooks**
+
+The `onReset` hook is triggered at runtime when files change or code recompilation (rspack) is needed. It is not part of the initialization flow, so it is not shown in the diagram above.
+
+- **Trigger Timing**: File changes (`event.type: 'file-change'`) or code recompilation (rspack) completion (`event.type: 'repack'`)
+- **Use Cases**: Clearing cache, re-initializing resources, etc.
+
+:::

package/docs/tutorials/examples/csr-auth.md

@@ -0,0 +1,9 @@
+# Route Authorization
+
+Modern.js defaults to the convention-based routing based on React Router. For more details, please refer to [Routing](/guides/basic-features/routes/routes.md#routing).
+
+In a web application, if there are multiple routes, we may need to authorize access to some of them before accessing them. For example, in the following scenario:
+
+- Access to the `/` route does not require authorization and can be accessed directly.
+- Access to the `/protected` route requires authorization. If there is no authorization, it will automatically redirect to the `/login` route. After successful login, it returns to `/protected`.
+

package/docs/tutorials/foundations/introduction.md

@@ -0,0 +1,16 @@
+# Modern.js Example Library
+
+Welcome to Modern.js Example Library! Here you'll find practical code examples to help you get started with Modern.js quickly.
+
+If you're new to Modern.js, we recommend reading the [Modern.js Introduction](/guides/get-started/introduction.md) first.
+
+## 📚 Example List
+
+- [Route Authorization](/tutorials/examples/csr-auth.md)
+- ...
+
+***
+
+## 💡 Contribute Examples
+
+If you have good examples to share, feel free to submit a PR on [GitHub](https://github.com/web-infra-dev/modern.js)!

package/package.json

@@ -17,7 +17,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.5.0-ultramodern.99",
+  "version": "3.8.1-ultramodern.2",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.js",
   "exports": {
@@ -68,6 +68,10 @@
     "./types": {
       "types": "./lib/types.d.ts",
       "default": "./lib/types.d.ts"
+    },
+    "./bundle-docs": {
+      "types": "./dist/types/bundleDocs.d.ts",
+      "default": "./dist/esm-node/bundleDocs.mjs"
     }
   },
   "engines": {
@@ -89,20 +93,34 @@
       ],
       "config": [
         "./dist/types/config/public.d.ts"
+      ],
+      "bundle-docs": [
+        "./dist/types/bundleDocs.d.ts"
       ]
     }
   },
   "bin": {
     "modern": "bin/modern.js",
-    "modern-app": "bin/modern.js"
+    "modern-app": "bin/modern.js",
+    "modern-bundle-docs": "bin/modern-bundle-docs.js"
   },
   "nx": {
     "targets": {
       "build": {
+        "dependsOn": [
+          "^build",
+          {
+            "projects": [
+              "@modern-js/main-doc"
+            ],
+            "target": "build"
+          }
+        ],
         "inputs": [
           "build",
           "^build",
-          "{workspaceRoot}/packages/document/docs/en/**/*"
+          "{workspaceRoot}/packages/document/doc_build/**/*.md",
+          "{workspaceRoot}/packages/document/doc_build/llms.txt"
         ],
         "outputs": [
           "{projectRoot}/dist",
@@ -116,16 +134,16 @@
     "@babel/traverse": "^8.0.0",
     "@babel/types": "^8.0.0",
     "@loadable/component": "5.16.7",
-    "@modern-js/builder": "npm:@bleedingdev/modern-js-builder@3.5.0-ultramodern.99",
-    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.5.0-ultramodern.99",
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.5.0-ultramodern.99",
-    "@modern-js/plugin-data-loader": "npm:@bleedingdev/modern-js-plugin-data-loader@3.5.0-ultramodern.99",
-    "@modern-js/prod-server": "npm:@bleedingdev/modern-js-prod-server@3.5.0-ultramodern.99",
-    "@modern-js/server": "npm:@bleedingdev/modern-js-server@3.5.0-ultramodern.99",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.5.0-ultramodern.99",
-    "@modern-js/server-utils": "npm:@bleedingdev/modern-js-server-utils@3.5.0-ultramodern.99",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.5.0-ultramodern.99",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.5.0-ultramodern.99",
+    "@modern-js/builder": "npm:@bleedingdev/modern-js-builder@3.8.1-ultramodern.2",
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.8.1-ultramodern.2",
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.8.1-ultramodern.2",
+    "@modern-js/plugin-data-loader": "npm:@bleedingdev/modern-js-plugin-data-loader@3.8.1-ultramodern.2",
+    "@modern-js/prod-server": "npm:@bleedingdev/modern-js-prod-server@3.8.1-ultramodern.2",
+    "@modern-js/server": "npm:@bleedingdev/modern-js-server@3.8.1-ultramodern.2",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.8.1-ultramodern.2",
+    "@modern-js/server-utils": "npm:@bleedingdev/modern-js-server-utils@3.8.1-ultramodern.2",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.8.1-ultramodern.2",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.8.1-ultramodern.2",
     "@rsbuild/core": "2.1.5",
     "@swc/core": "1.15.43",
     "@swc/helpers": "^0.5.23",
@@ -143,7 +161,7 @@
     "@rslib/core": "0.23.2",
     "@scripts/rstest-config": "2.66.0",
     "@types/babel__traverse": "7.28.0",
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.2.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
@@ -167,7 +185,7 @@
   },
   "scripts": {
     "dev": "rslib build --watch",
-    "build": "rslib build && pnpm -w tsgo:dts \"$PWD\" && pnpm run verify:public-surface && node ./scripts/copy-main-doc.mjs",
+    "build": "rslib build && pnpm -w tsgo:dts \"$PWD\" && pnpm run verify:public-surface && node ./bin/modern-bundle-docs.js",
     "verify:public-surface": "node ./tests/config/verify-public-surface.mjs",
     "test": "rstest"
   }

package/docs/_nav.json

@@ -1,36 +0,0 @@
-[
-  {
-    "text": "UltraModern Guide",
-    "link": "/guides/get-started/ultramodern",
-    "activeMatch": "/guides/"
-  },
-  {
-    "text": "configure",
-    "link": "/configure/app/usage",
-    "activeMatch": "/configure/"
-  },
-  {
-    "text": "plugin-menu",
-    "link": "/plugin/introduction",
-    "activeMatch": "/plugin/"
-  },
-  {
-    "text": "apis",
-    "link": "/apis/app/commands",
-    "activeMatch": "/apis/"
-  },
-  {
-    "text": "Examples",
-    "link": "/tutorials/foundations/introduction",
-    "activeMatch": "/tutorials/"
-  },
-  {
-    "text": "community",
-    "link": "/community/showcase",
-    "activeMatch": "/community/"
-  },
-  {
-    "text": "Upstream Modern.js 2.x Docs",
-    "link": "https://modernjs.dev/v2"
-  }
-]

package/docs/apis/_meta.json

@@ -1,13 +0,0 @@
-[
-  "app/commands",
-  {
-    "type": "dir",
-    "name": "app/hooks",
-    "label": "file-conventions"
-  },
-  {
-    "type": "dir",
-    "name": "app/runtime",
-    "label": "runtime-api"
-  }
-]

package/docs/apis/app/hooks/_meta.json

@@ -1,28 +0,0 @@
-[
-  {
-    "type": "dir",
-    "name": "src",
-    "label": "src/",
-    "collapsed": true
-  },
-  {
-    "type": "dir",
-    "name": "api",
-    "label": "api/",
-    "collapsed": true
-  },
-  {
-    "type": "dir",
-    "name": "server",
-    "label": "server/",
-    "collapsed": true
-  },
-  "shared",
-  {
-    "type": "dir",
-    "name": "config",
-    "label": "config/",
-    "collapsed": true
-  },
-  "modern-config"
-]

package/docs/apis/app/hooks/config/_meta.json

@@ -1 +0,0 @@
-["html", "favicon", "icon", "mock", "public", "upload"]

package/docs/apis/app/runtime/_meta.json

@@ -1,32 +0,0 @@
-[
-  {
-    "type": "dir",
-    "name": "core",
-    "label": "Core",
-    "collapsed": true
-  },
-  {
-    "type": "dir",
-    "name": "router",
-    "label": "Router",
-    "collapsed": true
-  },
-  {
-    "type": "dir",
-    "name": "ssr",
-    "label": "SSR",
-    "collapsed": true
-  },
-  {
-    "type": "dir",
-    "name": "bff",
-    "label": "BFF",
-    "collapsed": true
-  },
-  {
-    "type": "dir",
-    "name": "utility",
-    "label": "Utility",
-    "collapsed": true
-  }
-]

package/docs/components/build-output.mdx

@@ -1,45 +0,0 @@
-To build the production artifacts of the project, run `pnpm run build` in the project:
-
-```bash
-$ pnpm run build
-
-> modern build
-
-  Modern.js Framework
-
-info    Starting production build...
-info    Type checker is enabled. It may take some time.
-ready   Client compiled in 6.19 s
-info    Production file sizes:
-
-  File                                       Size        Gzipped
-  dist/routes-manifest.json                  0.74 kB     0.28 kB
-  dist/static/css/async/page.d7915515.css    1.4 kB      0.69 kB
-  dist/static/js/main.5ae469e7.js            3.0 kB      1.3 kB
-  dist/html/index/index.html                  6.0 kB      2.6 kB
-  dist/static/js/async/page.ddc8a4c1.js      19.2 kB     6.7 kB
-  dist/static/js/34.171fffdb.js              21.3 kB     7.1 kB
-  dist/static/js/lib-router.8995a55e.js      55.3 kB     18.1 kB
-  dist/static/js/lib-lodash.53ec3384.js      71.4 kB     24.8 kB
-  dist/static/js/lib-react.b5856db9.js       140.0 kB    45.2 kB
-  dist/static/js/lib-polyfill.86c452b3.js    213.3 kB    69.9 kB
-
-  Total size:  531.8 kB
-  Gzipped size:  176.7 kB
-```
-
-By default, the build artifacts are generated in `dist/`, with the following directory structure:
-
-```
-dist
-├── html
-│   └── index
-├── modern.config.json
-├── route.json
-├── routes-manifest.json
-└── static
-    ├── css
-    └── js
-```
-
-> If you need to customize the directory of the build artifacts, please refer to [Output files](/guides/basic-features/output-files).

package/docs/components/bundler.mdx

@@ -1,3 +0,0 @@
-Refers to module bundlers such as [Rspack](https://rspack.rs/).
-
-The main goal of bundlers is to bundle JavaScript, CSS and other files together, and the bundled files can be used in the browser, Node.js or other environments. When bundler processes the Web application, it builds a dependency graph and then combines every module into one or more bundles.

package/docs/components/debug-app.mdx

@@ -1,15 +0,0 @@
-Run `pnpm run dev` in the project to start the project:
-
-```bash
-$ pnpm run dev
-> modern dev
-
-  Modern.js Framework
-
-ready   Client compiled in 0.86 s
-
-  > Local:    http://localhost:8080/
-  > Network:  http://192.168.0.1:8080/
-```
-
-Open `http://localhost:8080/` in your browser to see the page content.

package/docs/components/default-browserslist.mdx

@@ -1,7 +0,0 @@
-
-```yaml title=".browserslistrc"
-chrome >= 87
-edge >= 88
-firefox >= 78
-safari >= 14
-```

package/docs/components/deploy-command.mdx

@@ -1,14 +0,0 @@
-## modern deploy
-
-The `modern deploy` command is used to generate artifacts required for the deployment platform.
-
-```bash
-Usage: modern deploy [options]
-
-Options:
-  -c --config <config>  Specify configuration file path, either relative or absolute
-  -s --skip-build       Skip the build stage
-  -h, --help            Display command help
-```
-
-For more details, refer to [Deploy Application](/guides/basic-features/deploy).

package/docs/components/deploy.mdx

@@ -1 +0,0 @@
-After local develop, you can refer to the [Deployment](/guides/basic-features/deploy.html) section to deploy the project to the server.

package/docs/components/enable-bff-caution.mdx

@@ -1,3 +0,0 @@
-:::tip
-Please refer to the [Enable BFF](/en/guides/advanced-features/bff/function.html#enable-bff) section in Basic Usage to enable BFF functionality first.
-:::

package/docs/components/enable-bff.mdx

@@ -1,56 +0,0 @@
-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
-  ]
-}
-```