@evjs/webpack-plugin 0.0.1-rc.6 → 0.0.1-rc.7

package/AGENT.md

@@ -1,10 +1,16 @@
-# @evjs/webpack-plugin
+# @evjs/webpack-plugin — Agent Guide
 
-Webpack adapter for the ev framework. Thin wrapper over `@evjs/build-tools`.
+> AI-agent reference for the `@evjs/webpack-plugin` package. This is an internal package used by `@evjs/cli` — application developers don't configure it directly.
+
+## Overview
+
+Webpack adapter wrapping `@evjs/build-tools`. Provides:
+1. **`EvWebpackPlugin`** — webpack plugin for server function discovery + child compilation
+2. **`server-fn-loader`** — webpack loader for `"use server"` file transforms
 
 ## EvWebpackPlugin
 
-Auto-discovers `"use server"` files, generates a server entry, spawns a Node-targeted child compiler, and emits `manifest.json`.
+Auto-discovers `"use server"` files, generates server entry, spawns a server-targeted child compiler, and emits `manifest.json`.
 
 ```js
 const { EvWebpackPlugin } = require("@evjs/webpack-plugin");
@@ -12,27 +18,83 @@ const { EvWebpackPlugin } = require("@evjs/webpack-plugin");
 new EvWebpackPlugin({
   server: {
     appFactory: "@evjs/runtime/server#createApp",       // default
-    runner: process.env.NODE_ENV === "development"
-      ? "@evjs/runtime/server#serve" : undefined,
-    setup: [],                                           // extra imports
+    runner: "@evjs/runtime/server#serve",                // for self-starting servers
+    middleware: ["./src/middleware/auth#default"],        // middleware imports
   },
 });
 ```
 
 ### Options
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `server.appFactory` | `string` | `"@evjs/runtime/server#createApp"` | App factory module ref |
-| `server.runner` | `string?` | `undefined` | Runner for self-starting server bundles |
-| `server.setup` | `string[]` | `[]` | Extra imports prepended to server entry |
+| `server.appFactory` | `string` | `"@evjs/runtime/server#createApp"` | Hono app factory module ref |
+| `server.runner` | `string?` | `undefined` | Runner module ref (e.g., `"@evjs/runtime/server#serve"`) |
+| `server.middleware` | `string[]` | `[]` | Middleware module refs prepended to server entry |
+
+### What It Does (Build Pipeline)
+
+1. **Discovery** — globs for `*.server.{ts,js,tsx,jsx}` in source tree
+2. **Client transform** — `server-fn-loader` replaces function bodies with `__ev_call` stubs
+3. **Server entry generation** — calls `generateServerEntry()` from `@evjs/build-tools`
+4. **Child compiler** — spawns a webpack child compilation targeting `node` with the server entry
+5. **Manifest emission** — writes `manifest.json` via `processAssets` hook
+
+### Output
+
+```
+dist/
+├── client/              # client webpack output
+│   ├── main.[hash].js
+│   └── index.html
+└── server/
+    ├── server.js        # server bundle (Node.js)
+    └── manifest.json    # server function registry
+```
+
+### Manifest Format
+
+```json
+{
+  "version": 1,
+  "serverFunctions": {
+    "abc123:getUsers": {
+      "module": "./api/users.server",
+      "export": "getUsers"
+    }
+  }
+}
+```
 
 ## server-fn-loader
 
-Webpack loader for `"use server"` files. Auto-detects client vs server compiler context.
+Webpack loader for `"use server"` files. Automatically detects whether it's running in the client or server compiler and applies the appropriate transform.
 
 ```js
-{ loader: "@evjs/webpack-plugin/server-fn-loader" }
+{
+  test: /\.server\.(ts|tsx|js|jsx)$/,
+  use: [
+    { loader: "swc-loader" },
+    { loader: "@evjs/webpack-plugin/server-fn-loader" },
+  ],
+}
 ```
 
-Client compiler → replaces function bodies with RPC stubs.
-Server compiler → keeps bodies, appends registrations, reports to manifest.
+**Client compiler** → replaces function bodies with `__ev_call` RPC stubs
+**Server compiler** → preserves function bodies, appends `registerServerFn()` calls
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | `EvWebpackPlugin` — main plugin |
+| `src/server-fn-loader.ts` | Webpack loader for `"use server"` transforms |
+
+## Integration with @evjs/cli
+
+`@evjs/cli` creates the webpack config in `create-webpack-config.ts`:
+
+1. Adds `EvWebpackPlugin` to plugins
+2. Adds `server-fn-loader` to module rules (before `swc-loader`)
+3. Configures dev server proxy for `/api/fn` → API server
+4. In dev mode, sets `runner` to `"@evjs/runtime/server#serve"` for auto-start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evjs/webpack-plugin",
-  "version": "0.0.1-rc.6",
+  "version": "0.0.1-rc.7",
   "description": "Webpack plugin and loaders for the ev framework",
   "type": "module",
   "publishConfig": {
@@ -36,8 +36,8 @@
   "author": "xusd320",
   "license": "MIT",
   "dependencies": {
-    "@evjs/build-tools": "0.0.1-rc.6",
-    "@evjs/manifest": "0.0.1-rc.6"
+    "@evjs/build-tools": "0.0.1-rc.7",
+    "@evjs/manifest": "0.0.1-rc.7"
   },
   "devDependencies": {
     "typescript": "^5.7.3",