@cfdez11/vex 0.4.0 → 0.6.0

package/client/services/hydrate-client-components.js

@@ -78,12 +78,12 @@
   // Start observing the document for new nodes
   observer.observe(document, { childList: true, subtree: true });
 
-  // Hydrate existing components on DOMContentLoaded or immediately if already interactive
+  // Hydrate existing components on DOMContentLoaded or immediately if already interactive.
+  // The observer is intentionally NOT disconnected here — it must stay active to catch
+  // components inserted after DOMContentLoaded (nested CSR components, Suspense streaming,
+  // SPA navigations). The `data-hydrated` guard in hydrateMarker prevents double-hydration.
   if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", () => {
-      hydrateComponents();
-      observer.disconnect();
-    });
+    document.addEventListener("DOMContentLoaded", () => hydrateComponents());
   } else {
     hydrateComponents();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfdez11/vex",
-  "version": "0.4.0",
+  "version": "0.6.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,8 @@
   "license": "MIT",
   "dependencies": {
     "dom-serializer": "^2.0.0",
+    "dotenv": "^16.0.0",
+    "esbuild": "^0.25.0",
     "express": "^5.2.1",
     "htmlparser2": "^10.0.0"
   }

package/server/build-static.js

@@ -1,3 +1,4 @@
+import "dotenv/config";
 import fs from "fs/promises";
 import path from "path";
 import { build } from "./utils/component-processor.js";

package/server/index.js

@@ -1,9 +1,9 @@
-import fs from "fs/promises";
+import "dotenv/config";
 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 +16,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 +28,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 +42,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 +56,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 +71,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")));
@@ -151,7 +116,7 @@ app.use(async (req, res) => {
   res.status(404).send("Page not found");
 });
 
-const PORT = process.env.PORT || 3001;
+const PORT = process.env.VEX_PORT || process.env.PORT || 3001;
 app.listen(PORT, () => {
   console.log(`Server running on port ${PORT}`);
 });

package/server/prebuild.js

@@ -1,3 +1,4 @@
+import "dotenv/config";
 import { build } from "./utils/component-processor.js";
 import { initializeDirectories } from "./utils/files.js";
 

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);
       }
     });
@@ -166,7 +177,7 @@ const getScriptImports = async (script, isClientSide = false, filePath = null) =
   while ((match = importRegex.exec(script)) !== null) {
     const [importStatement, defaultImport, namedImports, modulePath] = match;
 
-    const { path, fileUrl } = await getImportData(modulePath);
+    const { path, fileUrl } = await getImportData(modulePath, filePath);
 
     if (path.endsWith(".vex")) {
       // Recursively process HTML component
@@ -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;
 }
 
 /**
@@ -982,7 +989,7 @@ async function generateServerComponentHTML(componentPath) {
  * and runtime interpolations (e.g., `${variable}`).
  *
  * @param {string} componentName - The logical name of the component.
- * @param {string} originalPath - The original file path of the component.
+ * @param {string} componentAbsPath - The absolute file path of the component (resolved by getImportData).
  * @param {Record<string, any>} [props={}] - An object of props to pass to the component.
  *                                            Values can be literals or template
  *                                            interpolations (`${…}`) for dynamic evaluation.
@@ -990,16 +997,45 @@ async function generateServerComponentHTML(componentPath) {
  * @returns {Promise<string>} A promise that resolves to a string containing
  *                            the `<template>` HTML for hydration.
  */
-export async function processClientComponent(componentName, originalPath, props = {}) {
+export async function processClientComponent(componentName, componentAbsPath, props = {}) {
   const targetId = `client-${componentName}-${Date.now()}`;
 
-  const componentImport = generateComponentId(originalPath)
-  const propsJson = JSON.stringify(props);
+  // componentAbsPath is the absolute resolved path — generateComponentId strips ROOT_DIR
+  // internally, so this produces the same hash as the bundle filename written by
+  // generateComponentAndFillCache (which also calls generateComponentId with the abs path).
+  const componentImport = generateComponentId(componentAbsPath);
+  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 +1178,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 +1205,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 +1287,7 @@ async function generateComponentAndFillCache(filePath) {
           clientImports,
           clientComponents,
           componentName: generateComponentId(cacheKey),
+          componentFilePath: filePath,
         }))
       }
     }
@@ -1263,6 +1301,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/files.js

@@ -811,7 +811,7 @@ export async function saveClientComponentModule(componentName, jsModuleCode) {
  *   importPath: string
  * }}
  */
-export async function getImportData(importPath) {
+export async function getImportData(importPath, callerFilePath = null) {
   let resolvedPath;
   if (importPath.startsWith("vex/server/")) {
     resolvedPath = path.resolve(FRAMEWORK_DIR, importPath.replace("vex/server/", "server/"));
@@ -821,6 +821,11 @@ export async function getImportData(importPath) {
     resolvedPath = path.resolve(FRAMEWORK_DIR, importPath.replace(".app/server/", "server/"));
   } else if (importPath.startsWith(".app/")) {
     resolvedPath = path.resolve(FRAMEWORK_DIR, importPath.replace(".app/", ""));
+  } else if ((importPath.startsWith("./") || importPath.startsWith("../")) && callerFilePath) {
+    // Relative import — resolve against the caller component's directory, not ROOT_DIR.
+    // Without this, `import Foo from './foo.vex'` inside a nested component would be
+    // resolved from the project root instead of from the file that contains the import.
+    resolvedPath = path.resolve(path.dirname(callerFilePath), importPath);
   } else {
     resolvedPath = path.resolve(ROOT_DIR, importPath);
   }

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] ?? "";
     }
   }
 
@@ -127,7 +128,7 @@ async function renderClientComponents(html, clientComponents) {
   let processedHtml = html;
   const allScripts = [];
 
-  for (const [componentName, { originalPath }] of clientComponents.entries()) {
+  for (const [componentName, { path: componentAbsPath }] of clientComponents.entries()) {
     const escapedName = componentName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
     const componentRegex = new RegExp(
@@ -155,7 +156,7 @@ async function renderClientComponents(html, clientComponents) {
     for (let i = replacements.length - 1; i >= 0; i--) {
       const { start, end, attrs } = replacements[i];
 
-      const htmlComponent = await processClientComponent(componentName, originalPath, attrs);
+      const htmlComponent = await processClientComponent(componentName, componentAbsPath, attrs);
 
       processedHtml =
         processedHtml.slice(0, start) +