@modern-js/app-tools 3.7.0 → 3.8.0

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

@@ -15,7 +15,7 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.7.0",
+  "version": "3.8.0",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.js",
   "exports": {
@@ -54,6 +54,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": {
@@ -72,12 +76,41 @@
       ],
       "builder": [
         "./dist/types/builder/index.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/doc_build/**/*.md",
+          "{workspaceRoot}/packages/document/doc_build/llms.txt"
+        ],
+        "outputs": [
+          "{projectRoot}/dist",
+          "{projectRoot}/docs"
+        ]
+      }
+    }
   },
   "dependencies": {
     "@babel/parser": "^7.29.7",
@@ -93,16 +126,16 @@
     "ndepe": "^0.1.13",
     "pkg-types": "^1.3.1",
     "std-env": "^3.10.0",
-    "@modern-js/builder": "3.7.0",
-    "@modern-js/i18n-utils": "3.7.0",
-    "@modern-js/plugin": "3.7.0",
-    "@modern-js/prod-server": "3.7.0",
-    "@modern-js/plugin-data-loader": "3.7.0",
-    "@modern-js/server": "3.7.0",
-    "@modern-js/server-core": "3.7.0",
-    "@modern-js/server-utils": "3.7.0",
-    "@modern-js/types": "3.7.0",
-    "@modern-js/utils": "3.7.0"
+    "@modern-js/builder": "3.8.0",
+    "@modern-js/i18n-utils": "3.8.0",
+    "@modern-js/plugin-data-loader": "3.8.0",
+    "@modern-js/server": "3.8.0",
+    "@modern-js/prod-server": "3.8.0",
+    "@modern-js/plugin": "3.8.0",
+    "@modern-js/server-core": "3.8.0",
+    "@modern-js/types": "3.8.0",
+    "@modern-js/server-utils": "3.8.0",
+    "@modern-js/utils": "3.8.0"
   },
   "devDependencies": {
     "@rslib/core": "0.23.2",
@@ -133,7 +166,7 @@
   },
   "scripts": {
     "dev": "rslib build --watch",
-    "build": "rslib build",
+    "build": "rslib build && node ./bin/modern-bundle-docs.js",
     "test": "rstest"
   }
 }