evolit 0.1.0-alpha.1 → 0.1.0-alpha.11

package/README.md

@@ -38,7 +38,7 @@ Supported authored module extensions:
 
 ```sh
 yarn install
-npx evolit@alpha my-site
+npx -p evolit@alpha evolit my-site
 ```
 
 Additional commands:
@@ -61,7 +61,8 @@ yarn start
 The framework ships a starter at `templates/default`.
 
 `evolit <directory>` copies that template, writes a site `package.json`, and leaves the app ready
-to run. `evolit init <directory>` is supported as an explicit equivalent.
+to run. `evolit init <directory>` is supported as an explicit equivalent. The `npx -p … evolit`
+form keeps the CLI arguments unambiguous across npm versions.
 
 ## Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.11",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",
@@ -47,15 +47,16 @@
   },
   "dependencies": {
     "@jridgewell/remapping": "^2.3.5",
-    "@litsx/compiler": "0.9.5-canary-feat-ssr-20260726130435",
-    "@litsx/core": "0.17.0-canary-feat-ssr-20260726130435",
-    "@litsx/ssr": "0.2.0-canary-feat-ssr-20260726130435",
+    "@litsx/compiler": "0.9.5-canary-feat-ssr-20260726184312",
+    "@litsx/core": "0.17.0-canary-feat-ssr-20260726184312",
+    "@litsx/ssr": "0.2.0-canary-feat-ssr-20260726184312",
     "@litsx/typescript": "^0.9.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "lit": "^3.3.3",
     "magic-string": "^1.1.0",
     "rollup": "^4.46.1",
-    "typescript": "^6.0.0"
+    "typescript": "^6.0.0",
+    "ws": "^8.18.3"
   },
   "devDependencies": {
     "vite": "^8.1.5"

package/src/build.js

@@ -15,6 +15,7 @@ import {
   emitBundledClientAssets,
   emitHashedClientAssets,
   normalizeHydrationDataForClient,
+  resolveRouteClientImports,
   resolveSharedVendorModuleUrl,
   rewriteHydrationDataScript,
   rewriteServerAssetPlaceholders,
@@ -241,8 +242,11 @@ export async function buildProject(projectRoot) {
   );
   const ssrAdapter = createSsrAdapter({
     assetResolver,
-    async resolveAdditionalHead({ result }) {
-      const clientImports = Array.isArray(result.clientImports) ? result.clientImports : [];
+    async resolveAdditionalHead({ routeResult, result }) {
+      const clientImports = [
+        ...(Array.isArray(result.clientImports) ? result.clientImports : []),
+        ...resolveRouteClientImports(routeResult, projectRoot, clientAssets),
+      ];
       const urls = collectTransitiveAssetPreloads(clientImports, clientAssets);
       const styleUrls = collectTransitiveStyleUrls(clientImports, clientAssets);
 

package/src/cli.js

@@ -2,9 +2,7 @@
 
 import path from "node:path";
 import process from "node:process";
-import { buildProject } from "./build.js";
 import { scaffoldSite } from "./scaffold.js";
-import { createDevServer, createStartServer } from "./server.js";
 
 function parseArguments(argv) {
   const [command, ...rest] = argv;
@@ -55,12 +53,14 @@ async function run() {
   }
 
   if (command === "build") {
+    const { buildProject } = await import("./build.js");
     const manifestPath = await buildProject(projectRoot);
     console.log(`Built evolit app: ${path.relative(projectRoot, manifestPath)}`);
     return;
   }
 
   if (command === "start") {
+    const { createStartServer } = await import("./server.js");
     const server = await createStartServer(projectRoot, options);
     await server.listen();
     console.log(`evolit start listening on http://localhost:${server.port}`);
@@ -68,6 +68,7 @@ async function run() {
   }
 
   if (command === "dev") {
+    const { createDevServer } = await import("./server.js");
     const server = await createDevServer(projectRoot, options);
     await server.listen();
     console.log(`evolit dev listening on http://localhost:${server.port}`);

package/src/client-assets.js

@@ -57,6 +57,18 @@ function isRelativeSpecifier(specifier) {
   );
 }
 
+function stripImportSuffix(specifier) {
+  return specifier.split("?")[0].split("#")[0];
+}
+
+function resolveRelativeClientImportPath(fromClientModule, specifier) {
+  const normalizedSpecifier = stripImportSuffix(specifier);
+  return path
+    .normalize(path.join(path.dirname(fromClientModule), normalizedSpecifier))
+    .split(path.sep)
+    .join("/");
+}
+
 function parsePackageSpecifier(specifier) {
   if (!isBareSpecifier(specifier)) {
     return null;
@@ -1191,9 +1203,7 @@ function collectRelativeClientImportPaths(source, fileRelativePath, publicPathBy
       continue;
     }
 
-    const resolvedRelativePath = path.normalize(
-      path.join(path.dirname(fileRelativePath), specifier),
-    );
+    const resolvedRelativePath = resolveRelativeClientImportPath(fileRelativePath, specifier);
     if (!publicPathByRelativePath.has(resolvedRelativePath)) {
       continue;
     }
@@ -1217,9 +1227,7 @@ function rewriteRelativeClientImports(source, fileRelativePath, publicPathByRela
       continue;
     }
 
-    const resolvedRelativePath = path.normalize(
-      path.join(path.dirname(fileRelativePath), specifier),
-    );
+    const resolvedRelativePath = resolveRelativeClientImportPath(fileRelativePath, specifier);
     const rewrittenTarget = publicPathByRelativePath.get(resolvedRelativePath);
     if (!rewrittenTarget) {
       continue;
@@ -1776,6 +1784,28 @@ export function collectTransitiveAssetPreloads(publicUrls, assetManifest) {
   return discovered;
 }
 
+export function resolveRouteClientImports(routeResult, projectRoot, assetManifest) {
+  const normalizedManifest = normalizeClientAssetManifest(assetManifest);
+  if (!normalizedManifest) {
+    return [];
+  }
+
+  const routeModules = [
+    routeResult?.route?.page,
+    ...(routeResult?.route?.layouts ?? []),
+    routeResult?.boundaryModule,
+  ].filter((modulePath) => typeof modulePath === "string");
+
+  return [...new Set(routeModules.map((modulePath) => {
+    const relativePath = path.relative(projectRoot, modulePath).split(path.sep).join("/");
+    const extension = path.extname(relativePath);
+    const clientModule = extension
+      ? `${relativePath.slice(0, -extension.length)}.mjs`
+      : `${relativePath}.mjs`;
+    return normalizedManifest.byClientModule[clientModule] ?? null;
+  }).filter((publicUrl) => typeof publicUrl === "string"))];
+}
+
 export function collectTransitiveStyleUrls(publicUrls, assetManifest) {
   const normalizedManifest = normalizeClientAssetManifest(assetManifest);
   if (!normalizedManifest) {

package/src/compiler.js

@@ -17,6 +17,10 @@ import { ensureDirectory } from "./fs-utils.js";
 
 const MODULE_SPECIFIER_PATTERN =
   /\b(?:import|export)\s+(?:[^"']*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+const RESOLVABLE_IMPORT_EXTENSIONS = [
+  ...MODULE_EXTENSIONS,
+  ...STATIC_ASSET_EXTENSIONS,
+];
 
 function isRelativeSpecifier(specifier) {
   return specifier.startsWith("./") || specifier.startsWith("../");
@@ -44,6 +48,10 @@ function isStaticAssetPath(filePath) {
   return STATIC_ASSET_EXTENSIONS.some((extension) => filePath.endsWith(extension));
 }
 
+function hasResolvableImportExtension(filePath) {
+  return RESOLVABLE_IMPORT_EXTENSIONS.some((extension) => filePath.endsWith(extension));
+}
+
 function isStyleAssetPath(filePath) {
   return filePath.endsWith(".css");
 }
@@ -65,8 +73,8 @@ async function resolveImportPath(importerPath, specifier) {
   const basePath = path.resolve(path.dirname(importerPath), specifier);
   const candidates = [basePath];
 
-  if (!path.extname(basePath)) {
-    for (const extension of [...MODULE_EXTENSIONS, ...STATIC_ASSET_EXTENSIONS]) {
+  if (!hasResolvableImportExtension(basePath)) {
+    for (const extension of RESOLVABLE_IMPORT_EXTENSIONS) {
       candidates.push(`${basePath}${extension}`);
       candidates.push(path.join(basePath, `index${extension}`));
     }

package/src/deployment-runtime.js

@@ -12,6 +12,7 @@ import {
   getSharedOutputRoot,
   normalizeHydrationDataForClient,
   normalizeClientAssetManifest,
+  resolveRouteClientImports,
   resolveSharedVendorModuleUrl,
   resolveBrowserPackageAssetFilePath,
   rewriteHydrationDataScript,
@@ -233,8 +234,11 @@ export async function createRequestRenderer({ projectRoot, mode, assetManifest,
     assetResolver(moduleId) {
       return currentAssetResolver(moduleId);
     },
-    async resolveAdditionalHead({ result }) {
-      const clientImports = Array.isArray(result.clientImports) ? result.clientImports : [];
+    async resolveAdditionalHead({ routeResult, result }) {
+      const clientImports = [
+        ...(Array.isArray(result.clientImports) ? result.clientImports : []),
+        ...resolveRouteClientImports(routeResult, projectRoot, currentAssetManifest),
+      ];
       const urls = currentAssetManifest
         ? collectTransitiveAssetPreloads(clientImports, currentAssetManifest)
         : [];

package/src/scaffold.js

@@ -49,6 +49,10 @@ export async function scaffoldSite(targetDirectory, options = {}) {
   }
 
   await copyDirectory(TEMPLATE_ROOT, absoluteTargetDirectory);
+  await fs.rename(
+    path.join(absoluteTargetDirectory, "yarnrc.yml.template"),
+    path.join(absoluteTargetDirectory, ".yarnrc.yml"),
+  );
   await writeSitePackageJson(absoluteTargetDirectory, siteName);
   await fs.writeFile(
     path.join(absoluteTargetDirectory, "evolit.config.js"),

package/src/server.js

@@ -2,6 +2,7 @@ import http from "node:http";
 import { watch } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { WebSocketServer, WebSocket } from "ws";
 import { loadEvolitConfig } from "./config.js";
 import { createDeploymentRuntime } from "./deployment-runtime.js";
 import { APP_DIRECTORY, BUILD_DIRECTORY, INTERNAL_DIRECTORY, MANIFEST_FILENAME } from "./constants.js";
@@ -35,6 +36,36 @@ async function writeResponseBody(response, body) {
   response.end();
 }
 
+const LIVE_RELOAD_PATHNAME = "/_evolit/live-reload";
+
+function getResponseHeader(headers, name) {
+  if (headers?.get) {
+    return headers.get(name);
+  }
+
+  return headers?.[name] ?? headers?.[name.toLowerCase()] ?? null;
+}
+
+function injectLiveReloadSnippet(response) {
+  if (
+    typeof response.body !== "string"
+    || !getResponseHeader(response.headers, "content-type")?.includes("text/html")
+  ) {
+    return response;
+  }
+
+  return {
+    ...response,
+    body: response.body.includes("</body>")
+      ? response.body.replace("</body>", `${createLiveReloadSnippet()}</body>`)
+      : `${response.body}${createLiveReloadSnippet()}`,
+  };
+}
+
+function createLiveReloadSnippet() {
+  return `<script data-evolit-live-reload>const evolitProtocol=window.location.protocol==="https:"?"wss:":"ws:";const evolitSocket=new WebSocket(evolitProtocol+"//"+window.location.host+${JSON.stringify(LIVE_RELOAD_PATHNAME)});evolitSocket.addEventListener("message",({data})=>{if(data==="reload")window.location.reload()});</script>`;
+}
+
 async function createRecursiveDirectoryWatcher(rootDirectory, onChange) {
   const watchers = new Map();
   let closed = false;
@@ -122,6 +153,14 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
     responseCacheRuntime,
   });
   const port = getPort(explicitPort);
+  const liveReloadServer = mode === "development" ? new WebSocketServer({ noServer: true }) : null;
+  const liveReloadSockets = new Set();
+  liveReloadServer?.on("connection", (socket) => {
+    liveReloadSockets.add(socket);
+    socket.on("close", () => {
+      liveReloadSockets.delete(socket);
+    });
+  });
   let invalidationTimer = null;
   let pendingInvalidation = null;
   let resolvePendingInvalidation = null;
@@ -146,7 +185,17 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
       invalidationPromise = invalidationPromise
         .catch(() => {})
         .then(() => deploymentRuntime.invalidateDevelopmentState());
-      invalidationPromise.then(resolve, resolve);
+      invalidationPromise.then(
+        () => {
+          for (const socket of liveReloadSockets) {
+            if (socket.readyState === WebSocket.OPEN) {
+              socket.send("reload");
+            }
+          }
+          resolve();
+        },
+        resolve,
+      );
     }, 40);
   }
 
@@ -159,9 +208,10 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
 
   const server = http.createServer(async (req, res) => {
     try {
+      const origin = `http://${req.headers.host ?? `localhost:${port}`}`;
+      const pathname = new URL(req.url ?? "/", origin).pathname;
       await pendingInvalidation;
       await invalidationPromise;
-      const origin = `http://${req.headers.host ?? `localhost:${port}`}`;
       const method = req.method ?? "GET";
       const request = new Request(new URL(req.url ?? "/", origin), {
         method,
@@ -169,15 +219,31 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
         ...(method === "GET" || method === "HEAD" ? {} : { body: req, duplex: "half" }),
       });
       const response = await deploymentRuntime.handle(request);
+      const servedResponse = mode === "development"
+        ? injectLiveReloadSnippet(response)
+        : response;
 
-      res.writeHead(response.status, response.headers);
-      await writeResponseBody(res, response.body);
+      res.writeHead(servedResponse.status, servedResponse.headers);
+      await writeResponseBody(res, servedResponse.body);
     } catch (error) {
       res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
       res.end(error instanceof Error ? error.stack ?? error.message : String(error));
     }
   });
 
+  server.on("upgrade", (request, socket, head) => {
+    const origin = `http://${request.headers.host ?? `localhost:${port}`}`;
+    const pathname = new URL(request.url ?? "/", origin).pathname;
+    if (!liveReloadServer || pathname !== LIVE_RELOAD_PATHNAME) {
+      socket.destroy();
+      return;
+    }
+
+    liveReloadServer.handleUpgrade(request, socket, head, (webSocket) => {
+      liveReloadServer.emit("connection", webSocket, request);
+    });
+  });
+
   return {
     port,
     deploymentRuntime,
@@ -192,6 +258,14 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
         clearTimeout(invalidationTimer);
       }
       watcher?.close();
+      for (const socket of liveReloadSockets) {
+        socket.close();
+      }
+      if (liveReloadServer) {
+        await new Promise((resolve) => {
+          liveReloadServer.close(resolve);
+        });
+      }
       await new Promise((resolve, reject) => {
         server.close((error) => {
           if (error) {

package/templates/default/yarnrc.yml.template

@@ -0,0 +1 @@
+nodeLinker: node-modules