@evjs/cli 0.0.1-rc.15 → 0.0.1-rc.16

package/README.md

@@ -8,7 +8,7 @@
 npm install -g @evjs/cli
 ```
 
-## Zero-Config
+## Convention over Configuration
 
 No configuration file is needed. `ev dev` and `ev build` work out of the box with sensible defaults:
 
@@ -65,3 +65,35 @@ export default defineConfig({
 ```
 
 The `client.dev` and `server.dev` fields accept extra options that are merged with defaults.
+
+## Project Structure
+
+```
+my-app/
+├── ev.config.ts          # optional config
+├── index.html            # HTML template
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── main.tsx           # app bootstrap (keep minimal)
+    ├── routes.tsx         # route tree + components
+    ├── api/               # server functions
+    │   ├── users.server.ts
+    │   └── posts.server.ts
+    └── middleware/         # server middleware (optional)
+        └── auth.ts
+```
+
+## Common Mistakes
+
+1. **Don't create `webpack.config.cjs`** — use `ev.config.ts` instead
+2. **Don't install webpack manually** — it's a dependency of `@evjs/cli`
+3. **Config file must be `ev.config.ts`** — not `evjs.config.ts`
+4. **Import `defineConfig` from `@evjs/cli`** — not from `@evjs/runtime`
+
+## Bundled Dependencies
+
+Users do NOT need to install these — they're included in `@evjs/cli`:
+- `webpack`, `webpack-dev-server`
+- `html-webpack-plugin`, `swc-loader`, `@swc/core`
+- `@evjs/webpack-plugin`, `@evjs/build-tools`

package/dist/index.js

@@ -109,14 +109,14 @@ program
 /**
  * Load config and create webpack configuration object.
  *
- * Uses ev.config.ts when present, otherwise falls back to zero-config defaults.
+ * Uses ev.config.ts when present, otherwise falls back to convention-based defaults.
  * No webpack.config.cjs fallback — the meta-framework owns the build config.
  */
 async function resolveWebpackConfig(cwd) {
     const { loadConfig } = await import("./load-config.js");
     const evjsConfig = await loadConfig(cwd);
     const { createWebpackConfig } = await import("./create-webpack-config.js");
-    logger.info `Using ${evjsConfig ? "ev.config.ts" : "zero-config defaults"}`;
+    logger.info `Using ${evjsConfig ? "ev.config.ts" : "convention-based defaults"}`;
     const webpackConfig = createWebpackConfig(evjsConfig, cwd);
     return { evjsConfig, webpackConfig };
 }
@@ -136,51 +136,49 @@ program
         const devServerOptions = webpackConfig.devServer ?? {};
         const server = new WebpackDevServer(devServerOptions, compiler);
         await server.start();
-        // Background: wait for server bundle, then start Node API
-        void (async () => {
+        // Background: start Node API when server bundle is ready
+        let apiStarted = false;
+        compiler.hooks.done.tap("EvDevServer", async () => {
+            if (apiStarted)
+                return;
             const manifestPath = path.resolve(cwd, "dist/manifest.json");
             const bootstrapPath = path.resolve(cwd, "dist/server/_dev_start.cjs");
-            let started = false;
-            while (true) {
-                if (fs.existsSync(manifestPath)) {
-                    if (!started) {
-                        const runnerConfig = evjsConfig?.server?.runner ?? "node";
-                        const [runner, ...runnerExtraArgs] = runnerConfig.split(/\s+/);
-                        logger.info `Server bundle detected, starting ${runner} API...`;
-                        started = true;
-                        const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
-                        const serverBundlePath = path.resolve(cwd, "dist/server", manifest.server.entry);
-                        fs.writeFileSync(bootstrapPath, [
-                            `const bundle = require(${JSON.stringify(serverBundlePath)});`,
-                            `const app = bundle.createApp({ endpoint: ${JSON.stringify(evjsConfig?.server?.endpoint ?? CONFIG_DEFAULTS.endpoint)} });`,
-                            `const { serve } = require("@evjs/runtime/server/node");`,
-                            `serve(app, { port: ${serverPort} });`,
-                        ].join("\n"));
-                        // node gets --watch flags; other runtimes use their own args as-is
-                        const runnerArgs = runner === "node"
-                            ? [
-                                "--watch",
-                                "--watch-preserve-output",
-                                ...runnerExtraArgs,
-                                bootstrapPath,
-                            ]
-                            : [...runnerExtraArgs, bootstrapPath];
-                        try {
-                            await execa(runner, runnerArgs, {
-                                stdio: "inherit",
-                                env: { ...process.env, NODE_ENV: "development" },
-                            });
-                        }
-                        catch (_e) {
-                            started = false;
-                        }
-                    }
+            if (fs.existsSync(manifestPath)) {
+                apiStarted = true;
+                const backendConfig = evjsConfig?.server?.backend ?? "node";
+                const [backend, ...backendExtraArgs] = backendConfig.split(/\s+/);
+                logger.info `Server bundle detected, starting ${backend} API...`;
+                try {
+                    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+                    const serverBundlePath = path.resolve(cwd, "dist/server", manifest.server.entry);
+                    fs.writeFileSync(bootstrapPath, [
+                        `const bundle = require(${JSON.stringify(serverBundlePath)});`,
+                        `const app = bundle.createApp({ endpoint: ${JSON.stringify(evjsConfig?.server?.endpoint ?? CONFIG_DEFAULTS.endpoint)} });`,
+                        `const { serve } = require("@evjs/runtime/server/node");`,
+                        `serve(app, { port: ${serverPort} });`,
+                    ].join("\n"));
+                    // node gets --watch flags; other runtimes use their own args as-is
+                    const backendArgs = backend === "node"
+                        ? [
+                            "--watch",
+                            "--watch-preserve-output",
+                            ...backendExtraArgs,
+                            bootstrapPath,
+                        ]
+                        : [...backendExtraArgs, bootstrapPath];
+                    // Don't await execa here since it's a long-running watch process
+                    execa(backend, backendArgs, {
+                        stdio: "inherit",
+                        env: { ...process.env, NODE_ENV: "development" },
+                    }).catch(() => {
+                        apiStarted = false;
+                    });
+                }
+                catch (err) {
+                    logger.error `Server backend failed: ${err}`;
+                    apiStarted = false;
                 }
-                await new Promise((r) => setTimeout(r, 500));
             }
-        })().catch((err) => {
-            logger.error `Server runner failed: ${err}`;
-            process.exit(1);
         });
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evjs/cli",
-  "version": "0.0.1-rc.15",
+  "version": "0.0.1-rc.16",
   "description": "CLI and configuration layer for the evjs framework",
   "type": "module",
   "main": "./dist/config.js",
@@ -19,8 +19,7 @@
   },
   "files": [
     "dist",
-    "templates",
-    "AGENT.md"
+    "templates"
   ],
   "scripts": {
     "build": "tsc",
@@ -30,9 +29,9 @@
     "prepare": "npm run build"
   },
   "dependencies": {
-    "@evjs/webpack-plugin": "0.0.1-rc.15",
+    "@evjs/webpack-plugin": "*",
     "@logtape/logtape": "^2.0.4",
-    "@swc/core": "^1.2.147",
+    "@swc/core": "^1.15.18",
     "commander": "^12.1.0",
     "execa": "^9.5.2",
     "fs-extra": "^11.3.0",

package/templates/basic-csr/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-basic-csr",
-  "version": "0.0.1-rc.8",
+  "version": "0.0.0",
   "private": true,
   "scripts": {
     "dev": "ev dev",
@@ -8,12 +8,12 @@
     "check-types": "tsc --noEmit"
   },
   "dependencies": {
-    "@evjs/runtime": "^0.0.1-rc.15",
+    "@evjs/runtime": "*",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
   "devDependencies": {
-    "@evjs/cli": "^0.0.1-rc.5",
+    "@evjs/cli": "*",
     "@types/react": "^19.0.8",
     "@types/react-dom": "^19.0.3",
     "typescript": "^5.7.3"

package/templates/basic-server-fns/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-basic-server-fns",
-  "version": "0.0.1-rc.8",
+  "version": "0.0.0",
   "private": true,
   "scripts": {
     "dev": "ev dev",
@@ -8,12 +8,12 @@
     "check-types": "tsc --noEmit"
   },
   "dependencies": {
-    "@evjs/runtime": "^0.0.1-rc.15",
+    "@evjs/runtime": "*",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
   "devDependencies": {
-    "@evjs/cli": "^0.0.1-rc.5",
+    "@evjs/cli": "*",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.8",
     "typescript": "^5.7.3"

package/templates/complex-routing/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-complex-routing",
-  "version": "0.0.1-rc.8",
+  "version": "0.0.0",
   "private": true,
   "scripts": {
     "dev": "ev dev",
@@ -8,12 +8,12 @@
     "check-types": "tsc --noEmit"
   },
   "dependencies": {
-    "@evjs/runtime": "^0.0.1-rc.15",
+    "@evjs/runtime": "*",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
   "devDependencies": {
-    "@evjs/cli": "^0.0.1-rc.5",
+    "@evjs/cli": "*",
     "@types/react": "^19.0.8",
     "@types/react-dom": "^19.0.3",
     "typescript": "^5.7.3"

package/templates/configured-server-fns/ev.config.ts

@@ -4,7 +4,7 @@ import { defineConfig } from "@evjs/cli";
  * Advanced ev.config.ts example.
  *
  * This file demonstrates all available configuration options.
- * All fields are optional — evjs works zero-config out of the box.
+ * All fields are optional — evjs works out of the box.
  */
 export default defineConfig({
   client: {
@@ -39,9 +39,9 @@ export default defineConfig({
     // Server function endpoint path (default: "/api/fn")
     endpoint: "/api/fn",
 
-    // Server runner module (default: "@evjs/runtime/server/node")
+    // Server backend module (default: "@evjs/runtime/server/node")
     // For Deno/Bun/Workers, use: "@evjs/runtime/server/ecma"
-    runner: "@evjs/runtime/server/node",
+    backend: "@evjs/runtime/server/node",
 
     // Middleware module paths to auto-register in server entry
     // These are imported and applied in order

package/templates/configured-server-fns/package.json

@@ -1,6 +1,6 @@
 {
   "name": "example-configured-server-fns",
-  "version": "0.0.1-rc.8",
+  "version": "0.0.0",
   "private": true,
   "scripts": {
     "dev": "ev dev",
@@ -8,12 +8,12 @@
     "check-types": "tsc --noEmit"
   },
   "dependencies": {
-    "@evjs/runtime": "^0.0.1-rc.15",
+    "@evjs/runtime": "*",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
   "devDependencies": {
-    "@evjs/cli": "^0.0.1-rc.5",
+    "@evjs/cli": "*",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.8",
     "typescript": "^5.7.3"

package/AGENT.md

@@ -1,121 +0,0 @@
-# @evjs/cli — Agent Guide
-
-> AI-agent reference for developing apps with the `@evjs/cli` package.
-
-## Overview
-
-`@evjs/cli` is the CLI and configuration layer. Users install it as a devDependency. It provides:
-
-- **`ev init`** — scaffold a new project from templates
-- **`ev dev`** — start dev server (webpack-dev-server + API server)
-- **`ev build`** — production build (client + server bundles)
-- **`defineConfig`** — type-safe config export for `ev.config.ts`
-
-## Quick Start
-
-```bash
-npx @evjs/cli@latest init my-app
-cd my-app && npm install
-ev dev     # http://localhost:3000
-```
-
-## Configuration (`ev.config.ts`)
-
-Optional — everything works zero-config. Create `ev.config.ts` in project root when needed:
-
-```ts
-import { defineConfig } from "@evjs/cli";
-
-export default defineConfig({
-  client: {
-    entry: "./src/main.tsx",           // default
-    html: "./index.html",              // default
-    dev: {
-      port: 3000,                      // webpack-dev-server port
-      open: true,                      // auto-open browser
-      https: false,                    // enable HTTPS
-      historyApiFallback: true,        // SPA routing fallback
-    },
-    transport: {
-      baseUrl: "",                     // API base URL (for separate API host)
-      endpoint: "/api/fn",             // server function endpoint path
-    },
-  },
-  server: {
-    endpoint: "/api/fn",               // must match client transport endpoint
-    runner: "@evjs/runtime/server/node",
-    middleware: [
-      "./src/middleware/auth.ts",      // middleware module paths
-      "./src/middleware/logging.ts",
-    ],
-    dev: {
-      port: 3001,                      // API server port in dev mode
-    },
-  },
-});
-```
-
-### Config Defaults
-
-| Key | Default |
-|-----|---------|
-| `client.entry` | `"./src/main.tsx"` |
-| `client.html` | `"./index.html"` |
-| `client.dev.port` | `3000` |
-| `server.endpoint` | `"/api/fn"` |
-| `server.dev.port` | `3001` |
-| `server.runner` | `"@evjs/runtime/server/node"` |
-
-## Project Structure
-
-```
-my-app/
-├── ev.config.ts          # optional config
-├── index.html            # HTML template
-├── package.json
-├── tsconfig.json
-└── src/
-    ├── main.tsx           # app bootstrap (keep minimal)
-    ├── routes.tsx         # route tree + components
-    ├── api/               # server functions
-    │   ├── users.server.ts
-    │   └── posts.server.ts
-    └── middleware/         # server middleware (optional)
-        └── auth.ts
-```
-
-## CLI Commands
-
-### `ev init [project-name]`
-Interactive scaffolding. Templates:
-- `basic-csr` — client-side rendering only
-- `basic-server-fns` — server functions example
-- `configured-server-fns` — advanced config example
-- `complex-routing` — params, search, layouts, loaders
-
-### `ev dev`
-- Starts webpack-dev-server on port 3000
-- Auto-starts API server on port 3001
-- Proxies `/api/fn` requests to API server
-- Hot reloads client; restarts server on changes
-- `NODE_ENV=development`
-
-### `ev build`
-- Outputs client bundle to `dist/client/`
-- Outputs server bundle to `dist/server/`
-- Emits `dist/manifest.json` with server function registry
-- `NODE_ENV=production`
-
-## Common Mistakes
-
-1. **Don't create `webpack.config.cjs`** — use `ev.config.ts` instead
-2. **Don't install webpack manually** — it's a dependency of `@evjs/cli`
-3. **Config file must be `ev.config.ts`** — not `evjs.config.ts` or `evjs.config.ts`
-4. **Import `defineConfig` from `@evjs/cli`** — not from `@evjs/runtime`
-
-## Dependencies (bundled)
-
-Users do NOT need to install these — they're included in `@evjs/cli`:
-- `webpack`, `webpack-dev-server`, `webpack-cli`
-- `html-webpack-plugin`, `swc-loader`, `@swc/core`
-- `@evjs/webpack-plugin`