@cfdez11/vex 0.3.0 → 0.5.0

package/README.md

@@ -686,6 +686,12 @@ sequenceDiagram
 - [x] `vex.config.json` — configurable `srcDir` and `watchIgnore`
 - [x] Published to npm as `@cfdez11/vex`
 - [x] VS Code extension with syntax highlighting and go-to-definition
+- [ ] Devtools
+- [ ] Typescript in framework
+- [ ] Allow typescript to devs
+- [ ] Improve extension (hightlight, redirects, etc)
+- [ ] Create theme syntax
+- [ ] Create docs page
 - [ ] Authentication middleware
 - [ ] CDN cache integration
 - [ ] Fix Suspense marker replacement with multi-root templates

package/bin/vex.js

@@ -9,7 +9,25 @@ const serverDir = path.resolve(__dirname, "..", "server");
 
 const [command] = process.argv.slice(2);
 
+/**
+ * Available CLI commands.
+ *
+ * Each entry is a factory function that calls `spawn()` to launch a child
+ * process and returns the ChildProcess handle.
+ *
+ * `spawn(command, args, options)` forks a new OS process running `command`
+ * with the given `args`. It is non-blocking: the parent (this CLI) keeps
+ * running while the child executes. The returned ChildProcess emits an
+ * "exit" event when the child terminates, which we use to forward its exit
+ * code so the shell sees the correct status (e.g. for CI).
+ *
+ * `stdio: "inherit"` wires the child's stdin/stdout/stderr directly to the
+ * terminal that launched the CLI. Without it the child's output would be
+ * captured internally and never displayed. "inherit" is equivalent to
+ * passing [process.stdin, process.stdout, process.stderr].
+ */
 const commands = {
+  /** Start the dev server with Node's built-in file watcher (--watch restarts on .js changes). */
   dev: () =>
     spawn(
       "node",
@@ -17,6 +35,7 @@ const commands = {
       { stdio: "inherit" }
     ),
 
+  /** Run the prebuild: scan pages/, generate component bundles and route registries. */
   build: () =>
     spawn(
       "node",
@@ -24,16 +43,25 @@ const commands = {
       { stdio: "inherit" }
     ),
 
+  /** Start the production server. Sets NODE_ENV=production to disable HMR and file watchers. */
   start: () =>
     spawn(
       "node",
       [path.join(serverDir, "index.js")],
       { stdio: "inherit", env: { ...process.env, NODE_ENV: "production" } }
     ),
+
+  /** Run the static build: prebuild + copy assets to dist/ for deployment without a server. */
+  "build:static": () =>
+    spawn(
+      "node",
+      [path.join(serverDir, "build-static.js")],
+      { stdio: "inherit" }
+    ),
 };
 
 if (!commands[command]) {
-  console.error(`Unknown command: "${command}"\nAvailable: dev, build, start`);
+  console.error(`Unknown command: "${command}"\nAvailable: dev, build, build:static, start`);
   process.exit(1);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfdez11/vex",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A vanilla JavaScript meta-framework with file-based routing, SSR/CSR/SSG/ISR and Vue-like reactivity",
   "type": "module",
   "main": "./server/index.js",
@@ -22,6 +22,7 @@
   "license": "MIT",
   "dependencies": {
     "dom-serializer": "^2.0.0",
+    "esbuild": "^0.25.0",
     "express": "^5.2.1",
     "htmlparser2": "^10.0.0"
   }

package/server/build-static.js

@@ -0,0 +1,202 @@
+import fs from "fs/promises";
+import path from "path";
+import { build } from "./utils/component-processor.js";
+import {
+  initializeDirectories,
+  CLIENT_DIR,
+  SRC_DIR,
+  PROJECT_ROOT,
+  getRootTemplate,
+  WATCH_IGNORE,
+  generateComponentId,
+} from "./utils/files.js";
+
+const GENERATED_DIR = path.join(PROJECT_ROOT, ".vexjs");
+const DIST_DIR = path.join(PROJECT_ROOT, "dist");
+
+console.log("🔨 Starting static build...");
+
+// Step 1: Prebuild (components + routes)
+console.log("📁 Initializing directories...");
+await initializeDirectories();
+
+console.log("⚙️  Generating components and routes...");
+const { serverRoutes } = await build();
+
+// Step 2: Create dist/ structure (clean start)
+console.log("🗂️  Creating dist/ structure...");
+await fs.rm(DIST_DIR, { recursive: true, force: true });
+await fs.mkdir(path.join(DIST_DIR, "_vexjs", "_components"), { recursive: true });
+await fs.mkdir(path.join(DIST_DIR, "_vexjs", "user"), { recursive: true });
+
+// Step 3: Generate dist/index.html shell
+console.log("📄 Generating index.html shell...");
+const rootTemplate = await getRootTemplate();
+let shell = rootTemplate
+  .replace(/\{\{metadata\.title\}\}/g, "App")
+  .replace(/\{\{metadata\.description\}\}/g, "")
+  .replace(/\{\{props\.children\}\}/g, "");
+
+const frameworkScripts = [
+  `<script type="module" src="/_vexjs/services/index.js"></script>`,
+  `<script src="/_vexjs/services/hydrate-client-components.js"></script>`,
+  `<script src="/_vexjs/services/hydrate.js" id="hydrate-script"></script>`,
+].join("\n  ");
+
+shell = shell.replace("</head>", `  ${frameworkScripts}\n</head>`);
+await fs.writeFile(path.join(DIST_DIR, "index.html"), shell, "utf-8");
+
+// Step 4: Copy framework client files → dist/_vexjs/
+console.log("📦 Copying framework client files...");
+await fs.cp(CLIENT_DIR, path.join(DIST_DIR, "_vexjs"), { recursive: true });
+
+// Step 5: Copy generated component bundles → dist/_vexjs/_components/
+console.log("📦 Copying component bundles...");
+await fs.cp(
+  path.join(GENERATED_DIR, "_components"),
+  path.join(DIST_DIR, "_vexjs", "_components"),
+  { recursive: true }
+);
+
+// Step 6: Copy generated services (includes _routes.js) → dist/_vexjs/services/
+// This overwrites the framework-level services dir copy with the generated routes
+console.log("📦 Copying generated services...");
+await fs.cp(
+  path.join(GENERATED_DIR, "services"),
+  path.join(DIST_DIR, "_vexjs", "services"),
+  { recursive: true }
+);
+
+// Step 7: Copy user JS files with import rewriting → dist/_vexjs/user/
+console.log("📦 Processing user JS files...");
+await copyUserJsFiles(SRC_DIR, path.join(DIST_DIR, "_vexjs", "user"));
+
+// Step 8: Copy public/ → dist/ (static assets, CSS)
+console.log("📦 Copying public assets...");
+const publicDir = path.join(PROJECT_ROOT, "public");
+try {
+  await fs.cp(publicDir, DIST_DIR, { recursive: true });
+} catch {
+  // no public/ directory — that's fine
+}
+
+// Step 9: Copy pre-rendered HTML for SSG routes (revalidate: 'never')
+const CACHE_DIR = path.join(GENERATED_DIR, "_cache");
+const ssgRoutes = serverRoutes.filter(
+  (r) => r.meta.revalidate === "never" || r.meta.revalidate === false
+);
+if (ssgRoutes.length > 0) {
+  console.log("📄 Copying pre-rendered SSG pages...");
+  for (const route of ssgRoutes) {
+    const cacheFile = path.join(CACHE_DIR, `${generateComponentId(route.serverPath)}.html`);
+    try {
+      const html = await fs.readFile(cacheFile, "utf-8");
+      const routeSegment = route.serverPath === "/" ? "" : route.serverPath;
+      const destPath = path.join(DIST_DIR, routeSegment, "index.html");
+      await fs.mkdir(path.dirname(destPath), { recursive: true });
+      await fs.writeFile(destPath, html, "utf-8");
+      console.log(`   ✓ ${route.serverPath}`);
+    } catch {
+      console.warn(`   ✗ ${route.serverPath} (no cached HTML found)`);
+    }
+  }
+}
+
+// Step 10: Report SSR-only routes that were skipped
+const ssrOnlyRoutes = serverRoutes.filter((r) => r.meta.ssr);
+if (ssrOnlyRoutes.length > 0) {
+  console.warn("\n⚠️  The following routes require a server and were NOT included in the static build:");
+  for (const r of ssrOnlyRoutes) {
+    console.warn(`   ${r.path} (SSR)`);
+  }
+  console.warn("   These routes will show a 404 in the static build.\n");
+}
+
+console.log("✅ Static build complete! Output: dist/");
+console.log("\nTo serve locally:  npx serve dist");
+console.log("Static host note:  configure your host to serve dist/index.html for all 404s (SPA fallback).");
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Recursively walks SRC_DIR, rewrites imports in every .js file,
+ * and writes results to destDir preserving the relative path structure.
+ *
+ * Skips directories listed in WATCH_IGNORE (node_modules, dist, .vexjs, etc.).
+ *
+ * @param {string} srcDir  Absolute path to user source root (SRC_DIR)
+ * @param {string} destDir Absolute path to dist/_vexjs/user/
+ */
+async function copyUserJsFiles(srcDir, destDir) {
+  let entries;
+  try {
+    entries = await fs.readdir(srcDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (WATCH_IGNORE.has(entry.name)) continue;
+
+    const fullSrc = path.join(srcDir, entry.name);
+    const relToSrcDir = path.relative(SRC_DIR, fullSrc).replace(/\\/g, "/");
+    const fullDest = path.join(destDir, relToSrcDir);
+
+    if (entry.isDirectory()) {
+      await copyUserJsFiles(fullSrc, destDir);
+    } else if (entry.name.endsWith(".js")) {
+      let content;
+      try {
+        content = await fs.readFile(fullSrc, "utf-8");
+      } catch {
+        continue;
+      }
+
+      content = rewriteUserImports(content, fullSrc, srcDir);
+
+      await fs.mkdir(path.dirname(fullDest), { recursive: true });
+      await fs.writeFile(fullDest, content, "utf-8");
+    }
+  }
+}
+
+/**
+ * Rewrites import paths in a user JS file so they work in the browser.
+ * Mirrors the runtime rewriting done by the /_vexjs/user/* Express handler.
+ *
+ * - `vex/` and `.app/` → `/_vexjs/services/`
+ * - `@/` (project alias) → `/_vexjs/user/`
+ * - relative `./` or `../` → `/_vexjs/user/`
+ * - external bare specifiers (e.g. npm packages) → left as-is
+ *
+ * @param {string} content  File source
+ * @param {string} filePath Absolute path of the file being rewritten
+ * @param {string} srcDir   Absolute SRC_DIR root
+ * @returns {string} Rewritten source
+ */
+function rewriteUserImports(content, filePath, srcDir) {
+  return content.replace(
+    /^(\s*import\s+[^'"]*from\s+)['"]([^'"]+)['"]/gm,
+    (match, prefix, modulePath) => {
+      if (modulePath.startsWith("vex/") || modulePath.startsWith(".app/")) {
+        let mod = modulePath.replace(/^vex\//, "").replace(/^\.app\//, "");
+        if (!path.extname(mod)) mod += ".js";
+        return `${prefix}'/_vexjs/services/${mod}'`;
+      }
+      if (modulePath.startsWith("@/") || modulePath === "@") {
+        let resolved = path.resolve(srcDir, modulePath.replace(/^@\//, "").replace(/^@$/, ""));
+        if (!path.extname(resolved)) resolved += ".js";
+        const rel = path.relative(srcDir, resolved).replace(/\\/g, "/");
+        return `${prefix}'/_vexjs/user/${rel}'`;
+      }
+      if (modulePath.startsWith("./") || modulePath.startsWith("../")) {
+        const fileDir = path.dirname(filePath);
+        let resolved = path.resolve(fileDir, modulePath);
+        if (!path.extname(resolved)) resolved += ".js";
+        const rel = path.relative(srcDir, resolved).replace(/\\/g, "/");
+        return `${prefix}'/_vexjs/user/${rel}'`;
+      }
+      return match;
+    }
+  );
+}

package/server/index.js

@@ -1,9 +1,8 @@
-import fs from "fs/promises";
 import express from "express";
 import path from "path";
 import { pathToFileURL } from "url";
 import { handlePageRequest, revalidatePath } from "./utils/router.js";
-import { initializeDirectories, CLIENT_DIR, SRC_DIR } from "./utils/files.js";
+import { initializeDirectories, CLIENT_DIR } from "./utils/files.js";
 
 await initializeDirectories();
 
@@ -16,7 +15,7 @@ if (process.env.NODE_ENV === "production") {
     serverRoutes = routes;
     console.log("Routes loaded.");
   } catch {
-    console.error("ERROR: No build found. Run 'pnpm build' before starting in production.");
+    console.error("ERROR: No build found. Run 'vex build' before starting in production.");
     process.exit(1);
   }
 } else {
@@ -28,7 +27,9 @@ if (process.env.NODE_ENV === "production") {
 
 const app = express();
 
-// Serve generated client components at /_vexjs/_components/ (before broader /_vexjs mount)
+// Serve generated client component bundles at /_vexjs/_components/
+// Must be registered before the broader /_vexjs static mount below so that
+// .vexjs/_components/ takes priority over anything in CLIENT_DIR/_components/.
 app.use(
   "/_vexjs/_components",
   express.static(path.join(process.cwd(), ".vexjs", "_components"), {
@@ -40,7 +41,9 @@ app.use(
   })
 );
 
-// Serve generated services (e.g. _routes.js) at /_vexjs/services/ (before broader /_vexjs mount)
+// Serve generated services (e.g. _routes.js) at /_vexjs/services/
+// Also before the broader /_vexjs mount so the generated _routes.js
+// overrides any placeholder that might exist in the framework source.
 app.use(
   "/_vexjs/services",
   express.static(path.join(process.cwd(), ".vexjs", "services"), {
@@ -52,7 +55,10 @@ app.use(
   })
 );
 
-// Serve framework client files at /_vexjs/
+// Serve framework client runtime files at /_vexjs/
+// (reactive.js, html.js, hydrate.js, navigation/, etc.)
+// User imports like `vex/reactive` are marked external by esbuild and resolved
+// here at runtime — a single shared instance per page load.
 app.use(
   "/_vexjs",
   express.static(CLIENT_DIR, {
@@ -64,48 +70,6 @@ app.use(
   })
 );
 
-// Serve user JS utility files at /_vexjs/user/* with import rewriting
-app.get("/_vexjs/user/*splat", async (req, res) => {
-  const splat = req.params.splat;
-  const relPath = Array.isArray(splat) ? splat.join("/") : splat;
-  const filePath = path.resolve(path.join(SRC_DIR, relPath));
-  // Prevent path traversal outside SRC_DIR
-  if (!filePath.startsWith(SRC_DIR + path.sep) && filePath !== SRC_DIR) {
-    return res.status(403).send("Forbidden");
-  }
-  try {
-    let content = await fs.readFile(filePath, "utf-8");
-    // Rewrite imports to browser-accessible paths
-    content = content.replace(
-      /^(\s*import\s+[^'"]*from\s+)['"]([^'"]+)['"]/gm,
-      (match, prefix, modulePath) => {
-        if (modulePath.startsWith("vex/") || modulePath.startsWith(".app/")) {
-          let mod = modulePath.replace(/^vex\//, "").replace(/^\.app\//, "");
-          if (!path.extname(mod)) mod += ".js";
-          return `${prefix}'/_vexjs/services/${mod}'`;
-        }
-        if (modulePath.startsWith("@/") || modulePath === "@") {
-          let resolved = path.resolve(SRC_DIR, modulePath.replace(/^@\//, "").replace(/^@$/, ""));
-          if (!path.extname(resolved)) resolved += ".js";
-          const rel = path.relative(SRC_DIR, resolved).replace(/\\/g, "/");
-          return `${prefix}'/_vexjs/user/${rel}'`;
-        }
-        if (modulePath.startsWith("./") || modulePath.startsWith("../")) {
-          const fileDir = path.dirname(filePath);
-          let resolved = path.resolve(fileDir, modulePath);
-          if (!path.extname(resolved)) resolved += ".js";
-          const rel = path.relative(SRC_DIR, resolved).replace(/\\/g, "/");
-          return `${prefix}'/_vexjs/user/${rel}'`;
-        }
-        return match;
-      }
-    );
-    res.setHeader("Content-Type", "application/javascript");
-    res.send(content);
-  } catch {
-    res.status(404).send("Not found");
-  }
-});
 
 // Serve user's public directory at /
 app.use("/", express.static(path.join(process.cwd(), "public")));

package/server/utils/component-processor.js

@@ -1,10 +1,12 @@
 import { watch } from "fs";
 import path from "path";
+import esbuild from "esbuild";
 import { compileTemplateToHTML } from "./template.js";
-import { getOriginalRoutePath, getPageFiles, getRoutePath, saveClientComponentModule, saveClientRoutesFile, saveComponentHtmlDisk, saveServerRoutesFile, readFile, getImportData, generateComponentId, adjustClientModulePath, PAGES_DIR, ROOT_HTML_DIR, getLayoutPaths, SRC_DIR, WATCH_IGNORE, WATCH_IGNORE_FILES } from "./files.js";
+import { getOriginalRoutePath, getPageFiles, getRoutePath, saveClientComponentModule, saveClientRoutesFile, saveComponentHtmlDisk, saveServerRoutesFile, readFile, getImportData, generateComponentId, adjustClientModulePath, PAGES_DIR, ROOT_HTML_DIR, getLayoutPaths, SRC_DIR, WATCH_IGNORE, WATCH_IGNORE_FILES, CLIENT_COMPONENTS_DIR } from "./files.js";
 import { renderComponents } from "./streaming.js";
 import { getRevalidateSeconds } from "./cache.js";
 import { withCache } from "./data-cache.js";
+import { createVexAliasPlugin } from "./esbuild-plugin.js";
 
 /**
  * Throws a structured redirect error that propagates out of getData and is
@@ -107,7 +109,16 @@ if (process.env.NODE_ENV !== "production") {
         // 3. Notify connected browsers to reload
         hmrEmitter.emit("reload", filename);
       } else if (filename.endsWith(".js")) {
-        // User utility file changed — reload browsers (served dynamically, no bundle to regenerate)
+        // User utility .js file changed. Because esbuild inlines user files into
+        // each component bundle that imports them, a change to any utility requires
+        // re-bundling all components — we cannot know which bundles include this
+        // file without tracking the full import graph. Rebuilding all components
+        // is fast enough with esbuild (sub-millisecond per file).
+        try {
+          await generateComponentsAndFillCache();
+        } catch (e) {
+          console.error(`[HMR] Rebuild failed after ${filename} change:`, e.message);
+        }
         hmrEmitter.emit("reload", filename);
       }
     });
@@ -674,9 +685,22 @@ function convertVueToHtmlTagged(template, clientCode = "") {
 
   let result = template.trim();
 
+  // Self-closing x-for="item in items" → ${items.value.map(item => html`<Component ... />`)}
+  result = result.replace(
+    /<([\w-]+)([^>]*)\s+x-for="(\w+)\s+in\s+([^"]+)(?:\.value)?"([^>]*)\/>/g,
+    (_, tag, beforeAttrs, iterVar, arrayVar, afterAttrs) => {
+      const cleanExpr = arrayVar.trim();
+      const isSimpleVar = /^\w+$/.test(cleanExpr);
+      const arrayAccess = isSimpleVar && reactiveVars.has(cleanExpr)
+        ? `${cleanExpr}.value`
+        : cleanExpr;
+      return `\${${arrayAccess}.map(${iterVar} => html\`<${tag}${beforeAttrs}${afterAttrs} />\`)}`;
+    }
+  );
+
   // x-for="item in items" → ${items.value.map(item => html`...`)}
   result = result.replace(
-    /<(\w+)([^>]*)\s+x-for="(\w+)\s+in\s+([^"]+)(?:\.value)?"([^>]*)>([\s\S]*?)<\/\1>/g,
+    /<([\w-]+)([^>]*)\s+x-for="(\w+)\s+in\s+([^"]+)(?:\.value)?"([^>]*)>([\s\S]*?)<\/\1>/g,
     (_, tag, beforeAttrs, iterVar, arrayVar, afterAttrs, content) => {
       const cleanExpr = arrayVar.trim();
       const isSimpleVar = /^\w+$/.test(cleanExpr);
@@ -727,98 +751,41 @@ function convertVueToHtmlTagged(template, clientCode = "") {
 
 
 /**
- * Normalizes and deduplicates client-side ES module imports,
- * ensuring required framework imports are present.
+ * Generates and bundles a client-side JS module for a hydrated component using esbuild.
+ *
+ * Previously this function assembled the output by hand: it collected import statements,
+ * deduped them with getClientCodeImports, and concatenated everything into a JS string.
+ * That approach had two fundamental limitations:
+ *   1. npm package imports (bare specifiers like 'lodash') were left unresolved in the
+ *      output — the browser has no module resolver and would throw at runtime.
+ *   2. Transitive user utility files (@/utils/foo imported by @/utils/bar) were not
+ *      bundled; they were served on-the-fly at runtime by the /_vexjs/user/* handler,
+ *      adding an extra network round-trip per utility file on page load.
+ *
+ * With esbuild the entry source is passed via stdin and esbuild takes care of:
+ *   - Resolving and inlining @/ user imports and their transitive dependencies
+ *   - Resolving and bundling npm packages from node_modules
+ *   - Deduplicating shared modules across the bundle
+ *   - Writing the final ESM output directly to the destination file
+ *
+ * Framework singletons (vex/*, .app/*) are intentionally NOT bundled. They are
+ * marked external by the vex-aliases plugin so the browser resolves them at runtime
+ * from /_vexjs/services/, ensuring a single shared instance per page. Bundling them
+ * would give each component its own copy of reactive.js, breaking shared state.
  *
  * @async
- * @param {Record<string, {
- *   fileUrl: string,
- *   originalPath: string,
- *   importStatement: string
- * }>} clientImports
- *
- * @param {Record<string, string[]>} [requiredImports]
- *
- * @returns {Promise<string[]>}
- * Clean import statements.
- */
-async function getClientCodeImports(
-  clientImports,
-  requiredImports = {
-    "/_vexjs/services/reactive.js": ["effect"],
-    "/_vexjs/services/html.js": ["html"],
-  }
-) {
-
-  // Create a unique set of import statements to avoid duplicates
-  const cleanImportsSet = new Set(
-    Object.values(clientImports).map((importData) => importData.importStatement)
-  );
-  const cleanImports = Array.from(cleanImportsSet);
-
-  for (const [modulePath, requiredModules] of Object.entries(requiredImports)) {
-    const importIndex = cleanImports.findIndex((imp) =>
-      new RegExp(`from\\s+['"]${modulePath}['"]`).test(imp)
-    );
-
-    if (importIndex === -1) {
-      cleanImports.push(
-        `import { ${requiredModules.join(", ")} } from '${modulePath}';`
-      );
-    } else {
-      // if import exists, ensure it includes all required symbols
-      const existingImport = cleanImports[importIndex];
-      const importMatch = existingImport.match(/\{([^}]+)\}/);
-
-      if (importMatch) {
-        const importedModules = importMatch[1].split(",").map((s) => s.trim());
-        // Determine which required modules are missing
-        const missingModules = requiredModules.filter(
-          (s) => !importedModules.includes(s)
-        );
-        if (missingModules.length > 0) {
-          // Add missing symbols and reconstruct the import statement
-          importedModules.push(...missingModules);
-          cleanImports[importIndex] = existingImport.replace(
-            /\{[^}]+\}/,
-            `{ ${importedModules.join(", ")} }`
-          );
-        }
-      } else {
-        // If no named imports, convert to named imports
-        cleanImports[importIndex] = `import { ${requiredModules.join(
-          ", "
-        )} } from '${modulePath}';`;
-      }
-    }
-  }
-
-  // Return the final list of import statements
-  return cleanImports;
-}
-
-/**
- * Generates a client-side JS module for a hydrated component.
- *
- * The module:
- * - Includes required imports
- * - Injects default props
- * - Exports metadata
- * - Exposes a hydration entry point
- *
- * @async
- * @param {string} clientCode
- * @param {string} template
- * @param {object} metadata
- * @param {Record<string, {
- *  fileUrl: string,
- *  originalPath: string,
- *  importStatement: string
- *  }>} clientImports
- * 
+ * @param {{
+ *   clientCode: string,
+ *   template: string,
+ *   metadata: object,
+ *   clientImports: Record<string, { originalImportStatement: string }>,
+ *   clientComponents: Map<string, any>,
+ *   componentFilePath: string,
+ *   componentName: string,
+ * }} params
  *
- * @returns {Promise<string|null>}
- * Generated JS module code or null if no client code exists.
+ * @returns {Promise<null>}
+ * Always returns null — esbuild writes the bundle directly to disk.
  */
 export async function generateClientComponentModule({
   clientCode,
@@ -826,56 +793,96 @@ export async function generateClientComponentModule({
   metadata,
   clientImports,
   clientComponents,
+  componentFilePath,
+  componentName,
 }) {
+  if (!clientCode && !template) return null;
 
-  // Extract default props from xprops
+  // ── 1. Resolve default props from xprops() ─────────────────────────────────
   const defaults = extractVPropsDefaults(clientCode);
-
   const clientCodeWithProps = addComputedProps(clientCode, defaults);
 
-  // Remove xprops declaration and imports from client code
+  // ── 2. Build the function body: remove xprops declaration and import lines ──
+  // Imports are hoisted to module level in the entry source (step 4).
   const cleanClientCode = clientCodeWithProps
     .replace(/const\s+props\s*=\s*xprops\s*\([\s\S]*?\)\s*;?/g, "")
     .replace(/^\s*import\s+.*$/gm, "")
     .trim();
 
-  // Convert template
+  // ── 3. Convert Vue-like template syntax to html`` tagged template ───────────
   const convertedTemplate = convertVueToHtmlTagged(template, clientCodeWithProps);
+  const { html: processedHtml } = await renderComponents({ html: convertedTemplate, clientComponents });
+
+  // ── 4. Collect module-level imports for the esbuild entry source ────────────
+  // Use originalImportStatement (the specifier as written by the developer, before
+  // any path rewriting). esbuild receives the original specifiers and the alias
+  // plugin translates them at bundle time — no pre-rewriting needed here.
+  const importLines = new Set(
+    Object.values(clientImports)
+      .map((ci) => ci.originalImportStatement)
+      .filter(Boolean)
+  );
 
-  const { html: processedHtml } = await renderComponents({
-    html: convertedTemplate,
-    clientComponents,
-  });
-
-  const cleanImports = await getClientCodeImports(clientImports);
-
-  const clientComponentModule = `
-    ${cleanImports.join("\n")}  
-
-    export const metadata = ${JSON.stringify(metadata)}
-    
-    export function hydrateClientComponent(marker, incomingProps = {}) {
-      ${cleanClientCode}
-      
-      let root = null;
-      function render() {
-        const node = html\`${processedHtml}\`;
-        if (!root) {
-          root = node;
-          marker.replaceWith(node);
-        } else {
-          root.replaceWith(node);
-          root = node;
-        }
-      }
-
-      effect(() => render());
-
-      return root;
+  // Ensure effect and html are always available in the component body.
+  // If the developer already imported them the alias plugin's deduplication
+  // in esbuild's module graph handles the overlap — no duplicate at runtime.
+  const hasEffect = [...importLines].some((l) => /\beffect\b/.test(l));
+  const hasHtml = [...importLines].some((l) => /\bhtml\b/.test(l));
+  if (!hasEffect) importLines.add("import { effect } from 'vex/reactive';");
+  if (!hasHtml) importLines.add("import { html } from 'vex/html';");
+
+  // ── 5. Assemble the esbuild entry source ────────────────────────────────────
+  // This is a valid ESM module that esbuild will bundle. Imports at the top,
+  // hydrateClientComponent exported as a named function.
+  const entrySource = `
+${[...importLines].join("\n")}
+
+export const metadata = ${JSON.stringify(metadata)};
+
+export function hydrateClientComponent(marker, incomingProps = {}) {
+  ${cleanClientCode}
+
+  let root = null;
+  function render() {
+    const node = html\`${processedHtml}\`;
+    if (!root) {
+      root = node;
+      marker.replaceWith(node);
+    } else {
+      root.replaceWith(node);
+      root = node;
     }
-  `;
+  }
+
+  effect(() => render());
+  return root;
+}
+`.trim();
+
+  // ── 6. Bundle with esbuild ──────────────────────────────────────────────────
+  // stdin mode: esbuild receives the generated source as a virtual file.
+  // resolveDir tells esbuild which directory to use when resolving relative
+  // imports — it must be the .vex source file's directory so that './utils/foo'
+  // resolves relative to where the developer wrote the import, not relative to
+  // the framework's internal directories.
+  const outfile = path.join(CLIENT_COMPONENTS_DIR, `${componentName}.js`);
+
+  await esbuild.build({
+    stdin: {
+      contents: entrySource,
+      resolveDir: componentFilePath ? path.dirname(componentFilePath) : CLIENT_COMPONENTS_DIR,
+    },
+    bundle: true,
+    outfile,
+    format: "esm",
+    platform: "browser",
+    plugins: [createVexAliasPlugin()],
+    // Silence esbuild's default stdout logging — the framework has its own output
+    logLevel: "silent",
+  });
 
-  return clientComponentModule.trim();
+  // esbuild wrote directly to outfile — no string to return
+  return null;
 }
 
 /**
@@ -994,12 +1001,38 @@ export async function processClientComponent(componentName, originalPath, props
   const targetId = `client-${componentName}-${Date.now()}`;
 
   const componentImport = generateComponentId(originalPath)
-  const propsJson = JSON.stringify(props);
+  const propsJson = serializeClientComponentProps(props);
   const html = `<template id="${targetId}" data-client:component="${componentImport}" data-client:props='${propsJson}'></template>`;
   
   return html;
 }
 
+function isTemplateExpression(value) {
+  return typeof value === "string" && /^\$\{[\s\S]+\}$/.test(value.trim());
+}
+
+function serializeRuntimePropValue(value) {
+  if (!isTemplateExpression(value)) {
+    return JSON.stringify(value);
+  }
+
+  return value.trim().slice(2, -1).trim();
+}
+
+function serializeClientComponentProps(props = {}) {
+  const hasDynamicValues = Object.values(props).some(isTemplateExpression);
+
+  if (!hasDynamicValues) {
+    return JSON.stringify(props);
+  }
+
+  const serializedEntries = Object.entries(props).map(([key, value]) => {
+    return `${JSON.stringify(key)}: ${serializeRuntimePropValue(value)}`;
+  });
+
+  return `\${JSON.stringify({ ${serializedEntries.join(", ")} })}`;
+}
+
 /**
  * Extract xprops object literal from client code
  * @param {string} clientCode
@@ -1142,22 +1175,24 @@ function fillRoute(route, params) {
   });
 }
 /**
- * 
- * Generates js module and save it in public directory.
- * 
+ * Generates and saves the client-side JS bundle for a component.
+ *
+ * Delegates to generateClientComponentModule, which uses esbuild to bundle
+ * the component's <script client> code into a self-contained ESM file written
+ * directly to .vexjs/_components/<componentName>.js.
+ *
+ * componentFilePath is required so esbuild can resolve relative imports
+ * (./utils/foo) from the correct base directory.
+ *
  * @param {{
- *  metadata: object,
- *  clientCode: string,
- *  template: string,
- *  clientImports: Record<string, {
- *    fileUrl: string,
- *    originalPath: string,
- *    importStatement: string
- * }>,
- *  clientComponents: Record<string, any>,
- *  componentName: string,
- * }} 
- * 
+ *   metadata: object,
+ *   clientCode: string,
+ *   template: string,
+ *   clientImports: Record<string, { originalImportStatement: string }>,
+ *   clientComponents: Map<string, any>,
+ *   componentName: string,
+ *   componentFilePath: string,
+ * }} params
  * @returns {Promise<void>}
  */
 async function saveClientComponent({
@@ -1167,18 +1202,17 @@ async function saveClientComponent({
   clientImports,
   clientComponents,
   componentName,
+  componentFilePath,
 }) {
-  const jsModuleCode = await generateClientComponentModule({
+  await generateClientComponentModule({
     metadata,
     clientCode,
     template,
     clientImports,
     clientComponents,
+    componentFilePath,
+    componentName,
   });
-
-  if (jsModuleCode) {
-    await saveClientComponentModule(componentName, jsModuleCode)
-  }
 }
 
 /**x
@@ -1250,6 +1284,7 @@ async function generateComponentAndFillCache(filePath) {
           clientImports,
           clientComponents,
           componentName: generateComponentId(cacheKey),
+          componentFilePath: filePath,
         }))
       }
     }
@@ -1263,6 +1298,7 @@ async function generateComponentAndFillCache(filePath) {
       clientImports,
       clientComponents,
       componentName: generateComponentId(urlPath),
+      componentFilePath: filePath,
     }))
   }
 

package/server/utils/esbuild-plugin.js

@@ -0,0 +1,86 @@
+import path from "path";
+import { SRC_DIR } from "./files.js";
+
+/**
+ * Creates the VexJS esbuild alias plugin.
+ *
+ * esbuild resolves imports by looking at the specifier string (e.g. "vex/reactive",
+ * "./utils/counter", "lodash"). By default it only understands relative paths and
+ * node_modules. This plugin teaches esbuild about the three VexJS-specific import
+ * conventions so it can correctly bundle every <script client> block.
+ *
+ * The plugin intercepts imports at bundle time via onResolve hooks — each hook
+ * matches a filter regex against the import specifier and returns either:
+ *   - { path, external: true }  → esbuild leaves the import as-is in the output.
+ *                                  The browser resolves it at runtime from the URL.
+ *   - { path }                  → esbuild reads and inlines the file into the bundle.
+ *
+ * ─── Three categories of imports ────────────────────────────────────────────
+ *
+ * 1. Framework singletons  (vex/* and .app/*)
+ *    Examples: `import { reactive } from 'vex/reactive'`
+ *              `import { html } from '.app/html'`
+ *
+ *    These are framework runtime files served statically at /_vexjs/services/.
+ *    They MUST be marked external so every component shares the same instance
+ *    at runtime. If esbuild inlined them, each component bundle would get its
+ *    own copy of reactive.js — reactive state would not be shared across
+ *    components on the same page and the entire reactivity system would break.
+ *
+ *    The path is rewritten from the short alias to the browser-accessible URL:
+ *      vex/reactive  →  /_vexjs/services/reactive.js  (external)
+ *
+ * 2. Project alias  (@/*)
+ *    Example: `import { counter } from '@/utils/counter'`
+ *
+ *    @/ is a shorthand for the project SRC_DIR root. These are user JS utilities
+ *    that should be bundled into the component (not served separately). esbuild
+ *    receives the absolute filesystem path so it can read and inline the file.
+ *
+ * 3. Relative imports  (./ and ../)
+ *    Example: `import { fn } from './helpers'`
+ *
+ *    These are resolved automatically by esbuild using the `resolveDir` option
+ *    set on the stdin entry (the directory of the .vex file being compiled).
+ *    No custom hook is needed for these.
+ *
+ * 4. npm packages  (bare specifiers like 'lodash', 'date-fns')
+ *    Also resolved automatically by esbuild via node_modules lookup.
+ *    No custom hook is needed.
+ *
+ * @returns {import('esbuild').Plugin}
+ */
+export function createVexAliasPlugin() {
+  return {
+    name: "vex-aliases",
+    setup(build) {
+      // ── Category 1a: vex/* ────────────────────────────────────────────────
+      // Matches: 'vex/reactive', 'vex/html', 'vex/navigation', etc.
+      // Rewrites to the browser URL and marks external so esbuild skips bundling.
+      build.onResolve({ filter: /^vex\// }, (args) => {
+        let mod = args.path.replace(/^vex\//, "");
+        if (!path.extname(mod)) mod += ".js";
+        return { path: `/_vexjs/services/${mod}`, external: true };
+      });
+
+      // ── Category 1b: .app/* ───────────────────────────────────────────────
+      // Legacy alias for framework services. Same treatment as vex/*.
+      // Matches: '.app/reactive', '.app/html', etc.
+      build.onResolve({ filter: /^\.app\// }, (args) => {
+        let mod = args.path.replace(/^\.app\//, "");
+        if (!path.extname(mod)) mod += ".js";
+        return { path: `/_vexjs/services/${mod}`, external: true };
+      });
+
+      // ── Category 2: @/ project alias ─────────────────────────────────────
+      // Matches: '@/utils/counter', '@/lib/api', etc.
+      // Resolved to an absolute filesystem path so esbuild can read and bundle
+      // the file inline. No .js extension auto-appended here — esbuild does it.
+      build.onResolve({ filter: /^@\// }, (args) => {
+        let resolved = path.resolve(SRC_DIR, args.path.slice(2));
+        if (!path.extname(resolved)) resolved += ".js";
+        return { path: resolved };
+      });
+    },
+  };
+}

package/server/utils/streaming.js

@@ -30,19 +30,20 @@ import {
  */
 function parseAttributes(rawAttrs) {
   const attrs = {};
-  const regex = /:(\w+)=['"]([^'"]+)['"]|@(\w+)=['"]([^'"]+)['"]|(\w+)=['"]([^'"]+)['"]/g;
+  const regex =
+    /:([\w-]+)=(?:"([^"]*)"|'([^']*)')|@([\w-]+)=(?:"([^"]*)"|'([^']*)')|([\w:-]+)=(?:"([^"]*)"|'([^']*)')/g;
   let match;
   
   while ((match = regex.exec(rawAttrs)) !== null) {
     if (match[1]) {
       // Dynamic prop :prop
-      attrs[match[1]] = match[2];
-    } else if (match[3]) {
+      attrs[match[1]] = match[2] ?? match[3] ?? "";
+    } else if (match[4]) {
       // Event handler @event
-      attrs[match[3]] = match[4];
-    } else if (match[5]) {
+      attrs[match[4]] = match[5] ?? match[6] ?? "";
+    } else if (match[7]) {
       // Static prop
-      attrs[match[5]] = match[6];
+      attrs[match[7]] = match[8] ?? match[9] ?? "";
     }
   }