@cfdez11/vex 0.6.0 → 0.8.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/client/services/navigation.js

@@ -0,0 +1,6 @@
+// Barrel file for vex/navigation imports.
+// Components import { useRouteParams } from "vex/navigation" which esbuild
+// rewrites to /_vexjs/services/navigation.js (external). All re-exports go
+// through navigation/index.js so the browser module cache ensures the same
+// runtime instance is shared with the index.js bootstrap.
+export { useRouteParams, useQueryParams, navigate } from "./navigation/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfdez11/vex",
-  "version": "0.6.0",
+  "version": "0.8.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");
@@ -47,32 +46,50 @@ const frameworkScripts = [
 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 4: Copy static framework assets (favicon.ico, app.webmanifest) → dist/_vexjs/
+// JS runtime files live in .vexjs/services/ (copied in step 5) — no need to
+// copy CLIENT_DIR/services/ separately.
+console.log("📦 Copying framework assets...");
+for (const asset of ["favicon.ico", "app.webmanifest"]) {
+  try {
+    await fs.copyFile(
+      path.join(CLIENT_DIR, asset),
+      path.join(DIST_DIR, "_vexjs", asset)
+    );
+  } catch {
+    // asset not present — skip
+  }
+}
 
-// Step 5: Copy generated component bundles → dist/_vexjs/_components/
-console.log("📦 Copying component bundles...");
+// Step 5: Copy generated services → dist/_vexjs/services/
+// .vexjs/services/ already contains both framework JS (copied by initializeDirectories)
+// and generated files (_routes.js). One copy covers everything.
+console.log("📦 Copying services...");
 await fs.cp(
-  path.join(GENERATED_DIR, "_components"),
-  path.join(DIST_DIR, "_vexjs", "_components"),
+  path.join(GENERATED_DIR, "services"),
+  path.join(DIST_DIR, "_vexjs", "services"),
   { 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...");
+// Step 6: Copy generated component bundles → dist/_vexjs/_components/
+console.log("📦 Copying component bundles...");
 await fs.cp(
-  path.join(GENERATED_DIR, "services"),
-  path.join(DIST_DIR, "_vexjs", "services"),
+  path.join(GENERATED_DIR, "_components"),
+  path.join(DIST_DIR, "_vexjs", "_components"),
   { 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)
+// Step 8: Copy public/ → dist/
 console.log("📦 Copying public assets...");
 const publicDir = path.join(PROJECT_ROOT, "public");
 try {
@@ -81,7 +98,7 @@ try {
   // no public/ directory — that's fine
 }
 
-// Step 9: Copy pre-rendered HTML for SSG routes (revalidate: 'never')
+// Step 9: Copy pre-rendered SSG pages
 const CACHE_DIR = path.join(GENERATED_DIR, "_cache");
 const ssgRoutes = serverRoutes.filter(
   (r) => r.meta.revalidate === "never" || r.meta.revalidate === false
@@ -103,7 +120,7 @@ if (ssgRoutes.length > 0) {
   }
 }
 
-// Step 10: Report SSR-only routes that were skipped
+// Step 10: Report SSR-only routes (skipped in static build)
 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:");
@@ -117,87 +134,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();
 
@@ -29,8 +29,6 @@ if (process.env.NODE_ENV === "production") {
 const app = express();
 
 // 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"), {
@@ -42,9 +40,9 @@ app.use(
   })
 );
 
-// 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.
+// Serve framework runtime JS + generated files (_routes.js) at /_vexjs/services/
+// initializeDirectories() pre-populates this dir with framework files; build()
+// adds generated files (_routes.js). Single source of truth for all /_vexjs/services/*.
 app.use(
   "/_vexjs/services",
   express.static(path.join(process.cwd(), ".vexjs", "services"), {
@@ -56,10 +54,24 @@ app.use(
   })
 );
 
-// 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.
+// Serve pre-bundled user JS utility files at /_vexjs/user/
+// Registered before the generic /_vexjs mount so requests don't fall through
+// to CLIENT_DIR unnecessarily. esbuild bundles each file with npm packages
+// inlined; vex/*, @/*, and relative user imports stay external (singletons).
+app.use(
+  "/_vexjs/user",
+  express.static(USER_GENERATED_DIR, {
+    setHeaders(res, filePath) {
+      if (filePath.endsWith(".js")) {
+        res.setHeader("Content-Type", "application/javascript");
+      }
+    },
+  })
+);
+
+// Serve static framework assets (favicon.ico, app.webmanifest) from CLIENT_DIR.
+// Runtime JS files (reactive.js, index.js, etc.) are already in .vexjs/services/
+// via initializeDirectories() and are served by the /_vexjs/services route above.
 app.use(
   "/_vexjs",
   express.static(CLIENT_DIR, {
@@ -71,7 +83,6 @@ app.use(
   })
 );
 
-
 // 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,7 +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");
-const SERVER_UTILS_DIR = path.join(GENERATED_DIR);
+export const USER_GENERATED_DIR = path.join(GENERATED_DIR, "user");
 const ROOT_HTML_USER = path.join(PROJECT_ROOT, "root.html");
 const ROOT_HTML_DEFAULT = path.join(FRAMEWORK_DIR, "server", "root.html");
 export const ROOT_HTML_DIR = ROOT_HTML_USER;
@@ -133,13 +133,21 @@ export const ROOT_HTML_DIR = ROOT_HTML_USER;
  */
 export async function initializeDirectories() {
   try {
+    const servicesDir = path.join(GENERATED_DIR, "services");
     await Promise.all([
       fs.mkdir(GENERATED_DIR, { recursive: true }),
       fs.mkdir(CACHE_DIR, { recursive: true }),
       fs.mkdir(CLIENT_COMPONENTS_DIR, { recursive: true }),
-      fs.mkdir(path.join(GENERATED_DIR, "services"), { recursive: true }),
+      fs.mkdir(USER_GENERATED_DIR, { recursive: true }),
+      fs.mkdir(servicesDir, { recursive: true }),
     ]);
 
+    // Copy framework client runtime files into .vexjs/services/ so they are
+    // served by the /_vexjs/services static route alongside generated files
+    // like _routes.js. Generated files (prefixed with _) are written later by
+    // the build step and overwrite any stale copies here.
+    await fs.cp(CLIENT_SERVICES_DIR, servicesDir, { recursive: true });
+
     return true;
   } catch (err) {
     console.error("Failed to create cache directory:", err);
@@ -165,12 +173,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 +210,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 +823,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 +841,5 @@ export async function getImportData(importPath, callerFilePath = null) {
 
   const fileUrl = pathToFileURL(resolvedPath).href;
   return { path: resolvedPath, fileUrl, importPath };
-}
+}
+