@cfdez11/vex 0.6.0 → 0.7.0

package/README.md

@@ -128,7 +128,7 @@ Optional file at the project root.
 ```html
 <!-- pages/example/page.vex -->
 <script server>
-  import UserCard from "components/user-card.vex";
+  import UserCard from "@/components/user-card.vex";
 
   const metadata = { title: "My Page", description: "Page description" };
 
@@ -138,7 +138,7 @@ Optional file at the project root.
 </script>
 
 <script client>
-  import Counter from "components/counter.vex";
+  import Counter from "@/components/counter.vex";
 </script>
 
 <template>
@@ -204,11 +204,11 @@ Import them in any page or component:
 
 ```html
 <script server>
-  import UserCard from "components/user-card.vex";
+  import UserCard from "@/components/user-card.vex";
 </script>
 
 <script client>
-  import Counter from "components/counter.vex";
+  import Counter from "@/components/counter.vex";
 </script>
 
 <template>
@@ -361,8 +361,8 @@ Streams a fallback immediately while a slow component loads:
 
 ```html
 <script server>
-  import SlowCard   from "components/slow-card.vex";
-  import SkeletonCard from "components/skeleton-card.vex";
+  import SlowCard     from "@/components/slow-card.vex";
+  import SkeletonCard from "@/components/skeleton-card.vex";
 </script>
 
 <template>
@@ -553,12 +553,23 @@ Reference the stylesheet in `root.html`:
 
 ## 🔧 Framework API
 
-### Imports
+### Import conventions
 
-| Import | Context | Description |
-|--------|---------|-------------|
-| `vex/reactive` | `<script client>` | Reactivity engine (`reactive`, `computed`, `effect`, `watch`) |
-| `vex/navigation` | `<script client>` | Router utilities (`useRouteParams`, `useQueryParams`) |
+| Pattern | Example | Behaviour |
+|---------|---------|-----------|
+| `vex/*` | `import { reactive } from "vex/reactive"` | Framework singleton — shared instance across all components |
+| `@/*` | `import store from "@/utils/store.js"` | Project alias for your source root — also a singleton |
+| `./` / `../` | `import { fn } from "./helpers.js"` | Relative user file — also a singleton |
+| npm bare specifier | `import { format } from "date-fns"` | Bundled inline by esbuild |
+
+All user JS files (`@/` and relative) are pre-bundled at startup: npm packages are inlined, while `vex/*`, `@/*`, and relative imports stay external. The browser's ES module cache guarantees every import of the same file returns the same instance — enabling shared reactive state across components without a dedicated store library.
+
+### Client script imports
+
+| Import | Description |
+|--------|-------------|
+| `vex/reactive` | Reactivity engine (`reactive`, `computed`, `effect`, `watch`) |
+| `vex/navigation` | Router utilities (`useRouteParams`, `useQueryParams`) |
 
 ### Server script hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfdez11/vex",
-  "version": "0.6.0",
+  "version": "0.7.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",

package/server/build-static.js

@@ -5,11 +5,10 @@ import { build } from "./utils/component-processor.js";
 import {
   initializeDirectories,
   CLIENT_DIR,
-  SRC_DIR,
   PROJECT_ROOT,
   getRootTemplate,
-  WATCH_IGNORE,
   generateComponentId,
+  USER_GENERATED_DIR,
 } from "./utils/files.js";
 
 const GENERATED_DIR = path.join(PROJECT_ROOT, ".vexjs");
@@ -68,9 +67,15 @@ await fs.cp(
   { 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 7: Copy pre-bundled user JS files → dist/_vexjs/user/
+// build() already ran esbuild on every user .js file → USER_GENERATED_DIR.
+// npm packages are bundled inline; vex/*, @/*, relative imports stay external.
+console.log("📦 Copying pre-bundled user JS files...");
+try {
+  await fs.cp(USER_GENERATED_DIR, path.join(DIST_DIR, "_vexjs", "user"), { recursive: true });
+} catch {
+  // no user JS files — that's fine
+}
 
 // Step 8: Copy public/ → dist/ (static assets, CSS)
 console.log("📦 Copying public assets...");
@@ -117,87 +122,4 @@ 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

@@ -3,7 +3,7 @@ import express from "express";
 import path from "path";
 import { pathToFileURL } from "url";
 import { handlePageRequest, revalidatePath } from "./utils/router.js";
-import { initializeDirectories, CLIENT_DIR } from "./utils/files.js";
+import { initializeDirectories, CLIENT_DIR, USER_GENERATED_DIR } from "./utils/files.js";
 
 await initializeDirectories();
 
@@ -72,6 +72,22 @@ app.use(
 );
 
 
+// Serve pre-bundled user JS utility files at /_vexjs/user/
+// These are @/ and relative imports in <script client> blocks. esbuild bundles
+// each file with npm packages inlined; vex/*, @/*, and relative user imports
+// stay external so every component shares the same singleton module instance
+// via the browser's ES module cache.
+app.use(
+  "/_vexjs/user",
+  express.static(USER_GENERATED_DIR, {
+    setHeaders(res, filePath) {
+      if (filePath.endsWith(".js")) {
+        res.setHeader("Content-Type", "application/javascript");
+      }
+    },
+  })
+);
+
 // Serve user's public directory at /
 app.use("/", express.static(path.join(process.cwd(), "public")));
 

package/server/utils/component-processor.js

@@ -1,8 +1,9 @@
 import { watch } from "fs";
+import fs from "fs/promises";
 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, CLIENT_COMPONENTS_DIR } 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, USER_GENERATED_DIR } from "./files.js";
 import { renderComponents } from "./streaming.js";
 import { getRevalidateSeconds } from "./cache.js";
 import { withCache } from "./data-cache.js";
@@ -109,15 +110,12 @@ if (process.env.NODE_ENV !== "production") {
         // 3. Notify connected browsers to reload
         hmrEmitter.emit("reload", filename);
       } else if (filename.endsWith(".js")) {
-        // 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).
+        // Rebuild the changed user JS file so npm imports are re-bundled.
+        const fullPath = path.join(SRC_DIR, filename);
         try {
-          await generateComponentsAndFillCache();
+          await buildUserFile(fullPath);
         } catch (e) {
-          console.error(`[HMR] Rebuild failed after ${filename} change:`, e.message);
+          console.error(`[HMR] Failed to rebuild user file ${filename}:`, e.message);
         }
         hmrEmitter.emit("reload", filename);
       }
@@ -1557,6 +1555,59 @@ export async function generateRoutes() {
   return { serverRoutes };
 }
 
+/**
+ * Bundles a single user JS file with esbuild so npm bare-specifier imports
+ * are resolved and inlined, while vex/*, @/*, and relative user imports stay
+ * external (singletons served at /_vexjs/user/*).
+ *
+ * Output is written to USER_GENERATED_DIR preserving the SRC_DIR-relative path.
+ *
+ * @param {string} filePath - Absolute path to the user .js file.
+ */
+async function buildUserFile(filePath) {
+  const rel = path.relative(SRC_DIR, filePath).replace(/\\/g, "/");
+  const outfile = path.join(USER_GENERATED_DIR, rel);
+  await esbuild.build({
+    entryPoints: [filePath],
+    bundle: true,
+    format: "esm",
+    outfile,
+    plugins: [createVexAliasPlugin()],
+  });
+}
+
+/**
+ * Recursively finds all .js files in SRC_DIR (excluding WATCH_IGNORE dirs)
+ * and prebundles each one via buildUserFile.
+ *
+ * Called during build() so that user utility files are ready before the server
+ * starts serving /_vexjs/user/* from the pre-built static output.
+ */
+async function buildUserFiles() {
+  const collect = async (dir) => {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    await Promise.all(entries.map(async (entry) => {
+      if (WATCH_IGNORE.has(entry.name)) return;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await collect(full);
+      } else if (entry.name.endsWith(".js")) {
+        try {
+          await buildUserFile(full);
+        } catch (e) {
+          console.error(`[build] Failed to bundle user file ${full}:`, e.message);
+        }
+      }
+    }));
+  };
+  await collect(SRC_DIR);
+}
+
 /**
  * Single-pass build entry point.
  *
@@ -1573,5 +1624,6 @@ export async function generateRoutes() {
  */
 export async function build() {
   await generateComponentsAndFillCache();
+  await buildUserFiles();
   return generateRoutes();
 }

package/server/utils/esbuild-plugin.js

@@ -1,5 +1,5 @@
 import path from "path";
-import { SRC_DIR } from "./files.js";
+import { SRC_DIR, PROJECT_ROOT } from "./files.js";
 
 /**
  * Creates the VexJS esbuild alias plugin.
@@ -17,9 +17,8 @@ import { SRC_DIR } from "./files.js";
  *
  * ─── Three categories of imports ────────────────────────────────────────────
  *
- * 1. Framework singletons  (vex/* and .app/*)
+ * 1. Framework singletons  (vex/*)
  *    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
@@ -33,16 +32,20 @@ import { SRC_DIR } from "./files.js";
  * 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.
+ *    @/ is a shorthand for the project SRC_DIR root. These files are served as
+ *    singleton modules at /_vexjs/user/ — the browser's ES module cache ensures
+ *    all components share the same instance (same reactive state, same store).
  *
  * 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.
+ *    Treated the same as @/ — marked external and served at /_vexjs/user/.
+ *    This gives the same singleton guarantee as @/ imports: two components that
+ *    import the same file via different relative paths both resolve to the same
+ *    URL, so the browser module cache returns the same instance.
+ *
+ *    Note: .vex component imports are stripped from clientImports before
+ *    reaching esbuild, so this hook only fires for .js user utility files.
  *
  * 4. npm packages  (bare specifiers like 'lodash', 'date-fns')
  *    Also resolved automatically by esbuild via node_modules lookup.
@@ -63,23 +66,44 @@ export function createVexAliasPlugin() {
         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\//, "");
+      // ── Category 2: @/ project alias ─────────────────────────────────────
+      // Matches: '@/utils/counter', '@/store/ui-state', etc.
+      //
+      // These are user JS utilities that must behave as singletons — all
+      // components on a page must share the SAME module instance (same reactive
+      // state, same store). If esbuild inlined them, each component bundle would
+      // get its own copy and reactive state would not propagate across components.
+      //
+      // Solution: mark as external and rewrite to the browser-accessible URL
+      // /_vexjs/user/<path>.js. The dev server serves those files on-the-fly with
+      // import rewriting; the static build pre-copies them to dist/_vexjs/user/.
+      // The browser's ES module cache ensures a single instance is shared.
+      build.onResolve({ filter: /^@\// }, (args) => {
+        let mod = args.path.slice(2); // strip leading @/
         if (!path.extname(mod)) mod += ".js";
-        return { path: `/_vexjs/services/${mod}`, external: true };
+        return { path: `/_vexjs/user/${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));
+      // ── Category 3: relative imports (./ and ../) ─────────────────────────
+      // Matches: './helpers', '../utils/format', etc.
+      //
+      // User JS files imported relatively are also served as singleton modules
+      // at /_vexjs/user/<resolved-path>.js. This mirrors Vue + Vite: every source
+      // file gets its own URL, and the browser module cache ensures the same file
+      // is always the same instance regardless of how it was imported.
+      //
+      // Files outside SRC_DIR (e.g. node_modules reached via ../../) fall through
+      // to esbuild's default resolver and are bundled inline as usual.
+      build.onResolve({ filter: /^\.\.?\// }, (args) => {
+        let resolved = path.resolve(args.resolveDir, args.path);
         if (!path.extname(resolved)) resolved += ".js";
-        return { path: resolved };
+
+        // Only intercept .js user files — anything else (CSS, JSON, non-user) falls through
+        if (!resolved.endsWith(".js")) return;
+        if (!resolved.startsWith(SRC_DIR) && !resolved.startsWith(PROJECT_ROOT)) return;
+
+        const rel = path.relative(SRC_DIR, resolved).replace(/\\/g, "/");
+        return { path: `/_vexjs/user/${rel}`, external: true };
       });
     },
   };

package/server/utils/files.js

@@ -111,6 +111,7 @@ export const CLIENT_SERVICES_DIR = path.join(CLIENT_DIR, "services");
 const GENERATED_DIR = path.join(PROJECT_ROOT, ".vexjs");
 const CACHE_DIR = path.join(GENERATED_DIR, "_cache");
 export const CLIENT_COMPONENTS_DIR = path.join(GENERATED_DIR, "_components");
+export const USER_GENERATED_DIR = path.join(GENERATED_DIR, "user");
 const SERVER_UTILS_DIR = path.join(GENERATED_DIR);
 const ROOT_HTML_USER = path.join(PROJECT_ROOT, "root.html");
 const ROOT_HTML_DEFAULT = path.join(FRAMEWORK_DIR, "server", "root.html");
@@ -137,6 +138,7 @@ export async function initializeDirectories() {
       fs.mkdir(GENERATED_DIR, { recursive: true }),
       fs.mkdir(CACHE_DIR, { recursive: true }),
       fs.mkdir(CLIENT_COMPONENTS_DIR, { recursive: true }),
+      fs.mkdir(USER_GENERATED_DIR, { recursive: true }),
       fs.mkdir(path.join(GENERATED_DIR, "services"), { recursive: true }),
     ]);
 
@@ -165,12 +167,10 @@ export async function initializeDirectories() {
  *
  * @example
  * const result = adjustClientModulePath(
- *   '.app/reactive.js',
- *   "import userController from '.app/reactive.js';"
+ *   'vex/reactive',
+ *   "import { reactive } from 'vex/reactive';"
  * );
- * console.log(result.path); // '/.app/client/services/reactive.js'
- * console.log(result.importStatement); 
- * // "import userController from '/.app/client/services/reactive.js';"
+ * console.log(result.path); // '/_vexjs/services/reactive.js'
  */
 export function adjustClientModulePath(modulePath, importStatement, componentFilePath = null) {
   if (modulePath.startsWith("/_vexjs/")) {
@@ -204,8 +204,8 @@ export function adjustClientModulePath(modulePath, importStatement, componentFil
     return { path: adjustedPath, importStatement: adjustedImportStatement };
   }
 
-  // Framework imports (vex/ and .app/)
-  let relative = modulePath.replace(/^vex\//, "").replace(/^\.app\//, "");
+  // Framework imports (vex/)
+  let relative = modulePath.replace(/^vex\//, "");
   let adjustedPath = `/_vexjs/services/${relative}`;
 
   // Auto-resolve directory → index.js, bare name → .js
@@ -817,10 +817,8 @@ export async function getImportData(importPath, callerFilePath = null) {
     resolvedPath = path.resolve(FRAMEWORK_DIR, importPath.replace("vex/server/", "server/"));
   } else if (importPath.startsWith("vex/")) {
     resolvedPath = path.resolve(FRAMEWORK_DIR, "client/services", importPath.replace("vex/", ""));
-  } else if (importPath.startsWith(".app/server/")) {
-    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 === "@") {
+    resolvedPath = path.resolve(SRC_DIR, importPath.replace(/^@\//, "").replace(/^@$/, ""));
   } 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
@@ -837,4 +835,5 @@ export async function getImportData(importPath, callerFilePath = null) {
 
   const fileUrl = pathToFileURL(resolvedPath).href;
   return { path: resolvedPath, fileUrl, importPath };
-}
+}
+