ecopages 0.2.0-beta.3 → 0.2.0-beta.31

package/README.md

@@ -34,14 +34,14 @@ bun dev
 
 Server and build commands accept the following options. They automatically map to the equivalent environment variables for the underlying process:
 
-| Option                     | Env Var                 | Description                         |
-| :------------------------- | :---------------------- | :---------------------------------- |
-| `-p, --port <port>`        | `ECOPAGES_PORT`         | Server port (default 3000)          |
-| `-n, --hostname <host>`    | `ECOPAGES_HOSTNAME`     | Server hostname                     |
-| `-b, --base-url <url>`     | `ECOPAGES_BASE_URL`     | Base URL string                     |
-| `-d, --debug`              | `ECOPAGES_LOGGER_DEBUG` | Enables debug-level logging         |
-| `-r, --react-fast-refresh` |                         | Enables React Fast Refresh          |
-| `--runtime <runtime>`      |                         | Force execution via `bun` or `node` |
+| Option                     | Env Var                 | Description                                               |
+| :------------------------- | :---------------------- | :-------------------------------------------------------- |
+| `-p, --port <port>`        | `ECOPAGES_PORT`         | Server port (default 3000)                                |
+| `-n, --hostname <host>`    | `ECOPAGES_HOSTNAME`     | Server hostname                                           |
+| `-b, --base-url <url>`     | `ECOPAGES_BASE_URL`     | Base URL string                                           |
+| `-d, --debug`              | `ECOPAGES_LOGGER_DEBUG` | Enables debug logging and startup phase trace (see below) |
+| `-r, --react-fast-refresh` |                         | Enables React Fast Refresh                                |
+| `--runtime <runtime>`      |                         | Force execution via `bun` or `node`                       |
 
 ### Runtime Detection
 
@@ -63,6 +63,36 @@ ecopages dev --port 8080 --debug
 ecopages dev -r
 ```
 
+### Debug logging and startup trace
+
+Set these in `.env` or on the command line when diagnosing slow dev startup or first page load.
+
+| Env var                       | CLI                    | What you get                                                                                   |
+| :---------------------------- | :--------------------- | :--------------------------------------------------------------------------------------------- |
+| `ECOPAGES_LOGGER_DEBUG=true`  | `ecopages dev --debug` | Verbose `[@ecopages/core]` logs across the stack, plus **startup phase trace** lines on stderr |
+| `ECOPAGES_STARTUP_TRACE=true` | —                      | **Only** the phase trace (no extra debug noise). Useful when measuring first-open latency      |
+
+Trace lines are prefixed with `[ecopages:startup-trace]` and look like:
+
+```text
+[ecopages:startup-trace] phase=config-ready wallMs=1271
+[ecopages:startup-trace] phase=setupAppRuntimePlugins durationMs=714 wallMs=1999
+[ecopages:startup-trace] phase=route-registry durationMs=1 wallMs=2000
+[ecopages:startup-trace] phase=server-listen durationMs=45 wallMs=2046
+[ecopages:startup-trace] phase=first-request-ssr durationMs=5296 wallMs=12495
+[ecopages:startup-trace] summary path=/docs/getting-started/introduction bundleCount=13 clientBundleBytes=858396 wallMs=12496
+```
+
+Phases: config ready → runtime plugins → route registry → server listening → first request SSR. The summary includes bundle count and total client JS bytes for that first request.
+
+```bash
+# Focused perf trace only
+ECOPAGES_STARTUP_TRACE=true pnpm dev
+
+# Full debug + trace
+ecopages dev --debug
+```
+
 ## Ecosystem & Plugins
 
 Ecopages relies on a modular architecture. Core logic and framework integrations are published as `@ecopages/*` packages on [npm](https://www.npmjs.com/org/ecopages).

package/bin/launch-plan.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { parseEnv } from "node:util";
 import { SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME } from "@ecopages/core/utils/resolve-entry-file";
+const SERVER_BUNDLE_MANIFEST_FILENAME = "manifest.json";
 const nodeRequirePreload = import.meta.resolve("./node-require-preload.js");
 const tsxLoader = import.meta.resolve("tsx/esm");
 function getEnvFilePaths(nodeEnv) {
@@ -76,15 +77,38 @@ function inferLaunchMode(args, launchMode) {
   }
   return "start";
 }
+function resolveProductionServerEntry(cwd = process.cwd()) {
+  const manifestPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_MANIFEST_FILENAME);
+  if (existsSync(manifestPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+      if (parsed?.serverEntry) {
+        const fromManifest = path.isAbsolute(parsed.serverEntry) ? parsed.serverEntry : path.join(path.dirname(manifestPath), parsed.serverEntry);
+        if (existsSync(fromManifest)) {
+          return fromManifest;
+        }
+      }
+      if (parsed?.distDir) {
+        const fromDistDir = path.join(parsed.distDir, SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+        if (existsSync(fromDistDir)) {
+          return fromDistDir;
+        }
+      }
+    } catch {
+    }
+  }
+  const legacyPath = path.join(cwd, "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+  return existsSync(legacyPath) ? legacyPath : void 0;
+}
 function createLaunchPlan(args, options, entryFile, launchMode) {
   const resolvedOptions = options ?? {};
   const resolvedEntryFile = entryFile ?? "app.ts";
   const { envOverrides, env } = buildLaunchEnv(resolvedOptions);
   const runtime = detectRuntime(resolvedOptions);
   const resolvedLaunchMode = inferLaunchMode(args, launchMode);
-  const distServerApp = path.join(process.cwd(), "dist", SERVER_BUNDLE_DIR, SERVER_BUNDLE_FILENAME);
+  const distServerApp = resolveProductionServerEntry(process.cwd());
   const shouldUseBundle = usesProductionBundle(resolvedLaunchMode);
-  const useBundle = shouldUseBundle && existsSync(distServerApp);
+  const useBundle = shouldUseBundle && Boolean(distServerApp);
   if (shouldUseBundle && !useBundle) {
     throw new Error("No production bundle found. Run `ecopages build` before starting in production mode.");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ecopages",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.31",
   "description": "CLI utilities for Ecopages",
   "type": "module",
   "engines": {
@@ -32,7 +32,7 @@
     "ecopages": "bin/cli.js"
   },
   "dependencies": {
-    "@ecopages/core": "0.2.0-beta.3",
+    "@ecopages/core": "0.2.0-beta.31",
     "@ecopages/logger": "^0.2.3",
     "giget": "^2.0.0",
     "tsx": "^4.22.3"