@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

package/src/adapters/shared/port-manager.js

@@ -0,0 +1,196 @@
+import { createServer as createNetServer } from "node:net";
+import { createInterface } from "node:readline";
+function isPortInUseError(error) {
+  if (!(error instanceof Error) && (typeof error !== "object" || error === null)) {
+    return false;
+  }
+  const maybeErr = error;
+  const code = typeof maybeErr.code === "string" || typeof maybeErr.code === "number" ? String(maybeErr.code) : void 0;
+  const syscall = typeof maybeErr.syscall === "string" ? maybeErr.syscall : void 0;
+  const message = error instanceof Error ? error.message : String(maybeErr.message ?? "");
+  if (code === "EADDRINUSE") {
+    return true;
+  }
+  if (message.includes("EADDRINUSE")) {
+    return true;
+  }
+  if (syscall === "listen" && /is port \d+ in use\??/i.test(message)) {
+    return true;
+  }
+  return false;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isPortAvailable(port, hostname = "127.0.0.1") {
+  return new Promise((resolve) => {
+    const tester = createNetServer();
+    tester.once("error", () => resolve(false));
+    tester.once("listening", () => {
+      tester.close(() => resolve(true));
+    });
+    tester.listen(port, hostname);
+  });
+}
+function createDefaultPrompt(stdin, stdout) {
+  return async (message, timeoutMs) => {
+    stdout.write(`${message} `);
+    return await new Promise((resolve) => {
+      const rl = createInterface({ input: stdin, output: void 0, terminal: false });
+      let settled = false;
+      const finish = (value) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        rl.close();
+        stdout.write("\n");
+        resolve(value);
+      };
+      const timer = setTimeout(() => finish(true), timeoutMs);
+      rl.once("line", (line) => {
+        const answer = line.trim().toLowerCase();
+        if (answer === "" || answer === "y" || answer === "yes") {
+          finish(true);
+        } else {
+          finish(false);
+        }
+      });
+      rl.once("close", () => finish(true));
+    });
+  };
+}
+const PREVIEW_PORT_RELEASE_RACE_RETRIES = 2;
+const PREVIEW_PORT_FALLBACK_ATTEMPTS = 20;
+const PREVIEW_PORT_RELEASE_RACE_DELAY_MS = 100;
+const PREVIEW_PORT_AUTO_APPROVE_MS = 1e4;
+class PortManager {
+  startOnPort;
+  warn;
+  probePort;
+  prompt;
+  interactive;
+  autoApproveMs;
+  maxPortOffset;
+  releaseRaceRetries;
+  releaseRaceDelayMs;
+  constructor(options) {
+    this.startOnPort = options.startOnPort;
+    this.warn = options.warn;
+    this.probePort = options.probePort ?? isPortAvailable;
+    this.maxPortOffset = options.maxPortOffset ?? PREVIEW_PORT_FALLBACK_ATTEMPTS - 1;
+    this.releaseRaceRetries = options.releaseRaceRetries ?? PREVIEW_PORT_RELEASE_RACE_RETRIES;
+    this.releaseRaceDelayMs = options.releaseRaceDelayMs ?? PREVIEW_PORT_RELEASE_RACE_DELAY_MS;
+    this.autoApproveMs = options.autoApproveMs ?? PREVIEW_PORT_AUTO_APPROVE_MS;
+    this.interactive = typeof options.interactive === "boolean" ? options.interactive : Boolean(typeof process !== "undefined" && process.stdin?.isTTY && process.stdout?.isTTY);
+    if (options.prompt) {
+      this.prompt = options.prompt;
+    } else if (this.interactive) {
+      this.prompt = createDefaultPrompt(process.stdin, process.stdout);
+    } else {
+      this.prompt = void 0;
+    }
+  }
+  /**
+   * Binds the preview server to the preferred port.
+   *
+   * @remarks
+   * When the preferred port is free, binds it directly — no prompt, no
+   * fallback. The interactive prompt only fires on a genuine EADDRINUSE
+   * collision (TTY runs), and auto-approves after
+   * {@link PortManagerOptions.autoApproveMs}. In non-interactive (CI) runs,
+   * the manager falls back silently only when
+   * {@link BindPortOptions.allowPortFallback} is true (the default-port
+   * path); pinned ports rethrow EADDRINUSE so Docker-style fixed-port
+   * deployments fail loudly instead of silently moving.
+   */
+  async bind(options) {
+    const preferredPort = options.preferredPort;
+    const firstAttempt = await this.tryPort(preferredPort);
+    if (firstAttempt.status === "bound") {
+      return firstAttempt.boundPort;
+    }
+    if (firstAttempt.status === "factory-refused") {
+      return null;
+    }
+    await this.shouldFallback(preferredPort, options.allowPortFallback, firstAttempt.error);
+    return await this.fallForward(preferredPort);
+  }
+  async shouldFallback(preferredPort, allowPortFallback, error) {
+    if (this.interactive && this.prompt) {
+      const nextFree = await this.findNextFreePort(preferredPort);
+      const nextFreeSuffix = typeof nextFree === "number" ? ` (next free: ${nextFree})` : "";
+      const autoApproveHint = `auto-yes in ${Math.round(this.autoApproveMs / 1e3)}s`;
+      const message = `[@ecopages/core] Port ${preferredPort} is already in use${nextFreeSuffix}. Bind there instead? [Y/n] (${autoApproveHint})`;
+      const accepted = await this.prompt(message, this.autoApproveMs);
+      if (!accepted) {
+        throw error;
+      }
+      return;
+    }
+    if (!allowPortFallback) {
+      throw error;
+    }
+  }
+  async fallForward(preferredPort) {
+    for (let offset = 1; offset <= this.maxPortOffset; offset += 1) {
+      const candidatePort = preferredPort + offset;
+      const attempt = await this.tryPort(candidatePort);
+      if (attempt.status === "bound") {
+        this.warn?.(
+          `Port ${preferredPort} is in use; preview serving on port ${attempt.boundPort} instead. Pin the preview port with --port or ECOPAGES_PORT when a fixed binding is required.`
+        );
+        return attempt.boundPort;
+      }
+    }
+    return null;
+  }
+  /**
+   * Attempts to bind via {@link PortManagerOptions.startOnPort} on `port`,
+   * retrying EADDRINUSE collisions up to
+   * {@link PortManagerOptions.releaseRaceRetries} to ride through TIME_WAIT
+   * race release.
+   *
+   * @remarks
+   * Only EADDRINUSE is retryable. Any other error is rethrown synchronously
+   * rather than swallowed as a soft "port taken" result, so a misconfigured
+   * factory surfaces loudly instead of causing a silent fallback. A `null`
+   * return from the factory (no throw) is reported as `factory-refused`, not
+   * conflated with a real collision.
+   */
+  async tryPort(port) {
+    for (let attempt = 0; attempt < this.releaseRaceRetries; attempt += 1) {
+      try {
+        const bound = await this.startOnPort(port);
+        if (bound) {
+          return { status: "bound", boundPort: bound };
+        }
+        return { status: "factory-refused" };
+      } catch (error) {
+        if (!isPortInUseError(error)) {
+          throw error;
+        }
+        if (attempt === this.releaseRaceRetries - 1) {
+          return { status: "port-in-use", error };
+        }
+        await sleep(this.releaseRaceDelayMs);
+      }
+    }
+    return { status: "factory-refused" };
+  }
+  async findNextFreePort(startPort) {
+    for (let offset = 1; offset <= this.maxPortOffset; offset += 1) {
+      const candidate = startPort + offset;
+      if (await this.probePort(candidate)) {
+        return candidate;
+      }
+    }
+    return null;
+  }
+}
+export {
+  PortManager,
+  isPortAvailable,
+  isPortInUseError
+};

package/src/adapters/shared/runtime-app-bootstrap.d.ts

@@ -6,9 +6,10 @@ export type RuntimeBinding = {
     runtimeOrigin: string;
     serveOptions: Record<string, unknown>;
     watch: boolean;
+    /** Whether preview may bind to the next free port when the preferred port is busy. */
+    allowPortFallback: boolean;
 };
 export type StaticRuntimeMode = {
-    requiresFetchRuntime: boolean;
     canBuildWithoutRuntimeServer: boolean;
 };
 export declare function resolveServeRuntimeOrigin(serveOptions: {

package/src/adapters/shared/runtime-app-bootstrap.js

@@ -12,11 +12,13 @@ function resolveServeRuntimeOrigin(serveOptions) {
 }
 function resolveRuntimeBinding(options) {
   const env = options.env ?? process.env;
+  const portExplicitlyConfigured = options.cliArgs.port !== void 0 || Boolean(env.ECOPAGES_PORT) || options.serverOptions?.port !== void 0;
   const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : void 0) ?? DEFAULT_ECOPAGES_PORT;
   const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
   return {
     preferredPort,
     preferredHostname,
+    allowPortFallback: !portExplicitlyConfigured,
     runtimeOrigin: resolveServeRuntimeOrigin({
       hostname: preferredHostname,
       port: preferredPort
@@ -30,13 +32,8 @@ function resolveRuntimeBinding(options) {
   };
 }
 function resolveStaticRuntimeMode(options) {
-  const requiresFetchRuntime = options.appConfig.integrations.some(
-    (integration) => integration.staticBuildStep === "fetch"
-  );
-  const canBuildWithoutRuntimeServer = (options.cliArgs.build || options.cliArgs.preview) && !requiresFetchRuntime;
   return {
-    requiresFetchRuntime,
-    canBuildWithoutRuntimeServer
+    canBuildWithoutRuntimeServer: options.cliArgs.build || options.cliArgs.preview
   };
 }
 export {

package/src/adapters/shared/runtime-server-lifecycle.d.ts

@@ -0,0 +1,46 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { IHmrManager } from '../../types/public-types.js';
+import type { ProjectWatcher } from '../../watchers/project-watcher.js';
+/**
+ * Copies source `public/` into dist and ensures the resolved assets directory exists.
+ */
+export declare function prepareRuntimePublicDir(appConfig: EcoPagesAppConfig): void;
+/**
+ * Attaches the shared HMR manager to every integration exactly once per app config.
+ *
+ * @remarks
+ * Runtime plugin setup must not call `integration.setHmrManager()` directly. Adapters invoke
+ * this after the manager is enabled so late plugin init cannot double-bind integrations.
+ */
+export declare function attachHmrToIntegrations(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): void;
+/**
+ * @deprecated Use {@link attachHmrToIntegrations} instead.
+ */
+export declare function wireIntegrationHmrManagers(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): void;
+/**
+ * Injects the dev HMR runtime into adapter-level HTML responses when watch mode is active.
+ */
+export declare function maybeInjectAdapterHmrHtmlResponse(response: Response, options: {
+    watch: boolean;
+    hmrManager?: Pick<IHmrManager, 'isEnabled'>;
+    hostOwnsDevClient: boolean;
+}): Promise<Response>;
+/**
+ * Releases shared dev resources in a consistent order across server adapters.
+ *
+ * @remarks
+ * Bun calls `buildRuntime()` during `initialize()` when watch is enabled; Node defers
+ * runtime creation to `completeInitialization()`. Transport-specific setup stays in
+ * each adapter — only shared teardown lives here.
+ */
+export declare function disposeDevResources(options: {
+    projectWatcher: ProjectWatcher | null | undefined;
+    appConfig: EcoPagesAppConfig;
+    hmrManager: IHmrManager | null | undefined;
+    bridge: {
+        destroy(): void;
+    } | null | undefined;
+    previewHost: {
+        stop(): Promise<void>;
+    };
+}): Promise<void>;

package/src/adapters/shared/runtime-server-lifecycle.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
+import { disposeAppBuildRuntime } from "../../build/build-runtime.js";
+import { copyRuntimePublicDirIfChanged } from "./copy-runtime-public-dir.js";
+import { clearAppDevClientBridge } from "../../dev/client-bridge-registry.js";
+import { clearAppHmrManager } from "../../dev/hmr-manager-registry.js";
+import { injectHmrRuntimeIntoHtmlResponse, isHtmlResponse, shouldInjectHmrHtmlResponse } from "./hmr-html-response.js";
+function prepareRuntimePublicDir(appConfig) {
+  const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
+  if (fileSystem.exists(srcPublicDir)) {
+    copyRuntimePublicDirIfChanged(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
+  }
+  fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+}
+const attachedHmrApps = /* @__PURE__ */ new WeakSet();
+function attachHmrToIntegrations(appConfig, hmrManager) {
+  if (attachedHmrApps.has(appConfig)) {
+    return;
+  }
+  attachedHmrApps.add(appConfig);
+  for (const integration of appConfig.integrations) {
+    integration.setHmrManager(hmrManager);
+  }
+}
+function wireIntegrationHmrManagers(appConfig, hmrManager) {
+  attachHmrToIntegrations(appConfig, hmrManager);
+}
+async function maybeInjectAdapterHmrHtmlResponse(response, options) {
+  if (shouldInjectHmrHtmlResponse(options.watch, options.hmrManager, options.hostOwnsDevClient) && isHtmlResponse(response)) {
+    return injectHmrRuntimeIntoHtmlResponse(response);
+  }
+  return response;
+}
+async function disposeDevResources(options) {
+  await options.projectWatcher?.close();
+  await disposeAppBuildRuntime(options.appConfig);
+  options.hmrManager?.stop();
+  options.bridge?.destroy();
+  clearAppDevClientBridge(options.appConfig);
+  clearAppHmrManager(options.appConfig);
+  await options.previewHost.stop();
+}
+export {
+  attachHmrToIntegrations,
+  disposeDevResources,
+  maybeInjectAdapterHmrHtmlResponse,
+  prepareRuntimePublicDir,
+  wireIntegrationHmrManagers
+};

package/src/adapters/shared/server-adapter.d.ts

@@ -21,7 +21,8 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
     protected routeHandler: ServerRouteHandler;
     protected staticSiteGenerator: StaticSiteGenerator;
     protected staticBuilder: ServerStaticBuilder;
-    protected readonly schemaValidator: SchemaValidationService;
+    protected schemaValidator: SchemaValidationService;
+    protected hostOwnsDevClient: boolean;
     protected initializeSharedRouteHandling(options: {
         staticRoutes: StaticRoute[];
         hmrManager?: any;

package/src/adapters/shared/server-adapter.js

@@ -27,6 +27,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
   staticSiteGenerator;
   staticBuilder;
   schemaValidator = new SchemaValidationService();
+  hostOwnsDevClient = false;
   async initializeSharedRouteHandling(options) {
     await this.initSharedRouter();
     this.configureSharedResponseHandlers(options.staticRoutes, options.hmrManager);
@@ -76,7 +77,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
         const module = await serverModuleTranspiler.importModule({
           filePath,
           outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-route-modules"),
-          externalPackages: false,
+          externalPackages: true,
           transpileErrorMessage: (details) => `Error transpiling route module: ${details}`,
           noOutputMessage: (targetFilePath) => `No transpiled output generated for route module: ${targetFilePath}`
         });
@@ -115,7 +116,8 @@ class SharedServerAdapter extends AbstractServerAdapter {
       fileSystemResponseMatcher: this.fileSystemResponseMatcher,
       explicitStaticRouteMatcher,
       watch: !!this.options?.watch,
-      hmrManager
+      hmrManager,
+      hostOwnsDevClient: this.hostOwnsDevClient
     });
   }
   createSharedResponseHandlerDependencies(staticRoutes) {
@@ -164,8 +166,7 @@ class SharedServerAdapter extends AbstractServerAdapter {
       importServerModule: async (filePath) => await serverModuleTranspiler.importModule({
         filePath,
         outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
-        externalPackages: true,
-        bypassCache: this.options?.watch === true
+        externalPackages: true
       })
     });
   }
@@ -380,7 +381,10 @@ class SharedServerAdapter extends AbstractServerAdapter {
       const runtimePath = context.hmrManager.getRuntimePath();
       if (fileSystem.exists(runtimePath)) {
         return new Response(fileSystem.readFileAsBuffer(runtimePath), {
-          headers: { "Content-Type": "application/javascript" }
+          headers: {
+            "Content-Type": "application/javascript",
+            "Cache-Control": "no-store, must-revalidate"
+          }
         });
       }
     }
@@ -389,7 +393,10 @@ class SharedServerAdapter extends AbstractServerAdapter {
       const assetPath = path.join(context.hmrManager.getDistDir(), relativePath);
       if (fileSystem.exists(assetPath)) {
         return new Response(fileSystem.readFileAsBuffer(assetPath), {
-          headers: { "Content-Type": "application/javascript" }
+          headers: {
+            "Content-Type": "application/javascript",
+            "Cache-Control": "no-store, must-revalidate"
+          }
         });
       }
     }

package/src/adapters/shared/server-route-handler.d.ts

@@ -16,6 +16,8 @@ export interface ServerRouteHandlerParams {
     watch?: boolean;
     /** HMR manager for broadcasting hot module reload events in development. */
     hmrManager?: IHmrManager;
+    /** When true, the host dev server owns browser dev-client bootstrap. */
+    hostOwnsDevClient?: boolean;
 }
 /**
  * Handles HTTP requests and routing for the server.
@@ -33,12 +35,13 @@ export declare class ServerRouteHandler {
     private readonly explicitStaticRouteMatcher?;
     private readonly watch;
     private readonly hmrManager?;
+    private readonly hostOwnsDevClient;
     /**
      * Creates a new ServerRouteHandler instance.
      *
      * @param params - Configuration parameters
      */
-    constructor({ router, fileSystemResponseMatcher, explicitStaticRouteMatcher, watch, hmrManager, }: ServerRouteHandlerParams);
+    constructor({ router, fileSystemResponseMatcher, explicitStaticRouteMatcher, watch, hmrManager, hostOwnsDevClient, }: ServerRouteHandlerParams);
     /**
      * Determines if HMR script should be injected.
      *

package/src/adapters/shared/server-route-handler.js

@@ -7,6 +7,7 @@ class ServerRouteHandler {
   explicitStaticRouteMatcher;
   watch;
   hmrManager;
+  hostOwnsDevClient;
   /**
    * Creates a new ServerRouteHandler instance.
    *
@@ -17,13 +18,15 @@ class ServerRouteHandler {
     fileSystemResponseMatcher,
     explicitStaticRouteMatcher,
     watch = false,
-    hmrManager
+    hmrManager,
+    hostOwnsDevClient = false
   }) {
     this.router = router;
     this.fileSystemResponseMatcher = fileSystemResponseMatcher;
     this.explicitStaticRouteMatcher = explicitStaticRouteMatcher;
     this.watch = watch;
     this.hmrManager = hmrManager;
+    this.hostOwnsDevClient = hostOwnsDevClient;
   }
   /**
    * Determines if HMR script should be injected.
@@ -31,7 +34,7 @@ class ServerRouteHandler {
    * @returns true if in watch mode and HMR manager is enabled
    */
   shouldInjectHmrScript() {
-    return shouldInjectHmrHtmlResponse(this.watch, this.hmrManager);
+    return shouldInjectHmrHtmlResponse(this.watch, this.hmrManager, this.hostOwnsDevClient);
   }
   /**
    * Checks if a response contains HTML content.

package/src/adapters/shared/server-static-builder.d.ts

@@ -1,11 +1,12 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { ApiHandler, StaticRoute } from '../../types/public-types.js';
+import type { EcoPagesAppConfig, IHmrManager } from '../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { StaticRoute } from '../../types/public-types.js';
 import type { RouteRegistry } from '../../router/server/route-registry.js';
 import type { StaticSiteGenerator } from '../../static-site-generator/static-site-generator.js';
 import type { StaticGenerationRendererResolver } from '../../route-renderer/route-renderer.js';
 export interface StaticBuildOptions {
-    preview?: boolean;
     baseUrl?: string;
+    force?: boolean;
 }
 export interface ServeOptions {
     hostname?: string;
@@ -15,10 +16,17 @@ export interface ServerStaticBuilderParams {
     appConfig: EcoPagesAppConfig;
     staticSiteGenerator: StaticSiteGenerator;
     serveOptions: ServeOptions;
-    apiHandlers?: ApiHandler[];
+    runtimeOrigin: string;
+    /**
+     * Whether the app requires a server entry bundle for production use.
+     * When `true`, the build step bundles the server entry file for `ecopages start`.
+     * Defaults to `false` (static-only build, no server needed).
+     */
+    needsServerBundle?: boolean;
     logger?: ServerStaticBuilderLogger;
-    previewServerFactory?: ServerStaticPreviewServerFactory;
     entryFile?: string;
+    hmrManager?: IHmrManager;
+    onRuntimePlugin?: (plugin: EcoBuildPlugin) => void;
 }
 /**
  * Minimal logger dependency used by the static builder.
@@ -29,50 +37,34 @@ export interface ServerStaticBuilderLogger {
     error(message: string): unknown;
 }
 /**
- * Preview server factory dependency used when static preview mode is enabled.
- */
-export interface ServerStaticPreviewServerFactory {
-    createServer(args: {
-        appConfig: EcoPagesAppConfig;
-        options: {
-            port: number;
-        };
-    }): {
-        server?: {
-            port?: number;
-        } | null;
-    };
-}
-/**
- * Handles static site generation and previews.
+ * Handles static site generation.
  */
 export declare class ServerStaticBuilder {
     private readonly appConfig;
     private readonly staticSiteGenerator;
     private readonly serveOptions;
-    private readonly apiHandlers;
+    private readonly runtimeOrigin;
+    private readonly needsServerBundle;
     private readonly logger;
-    private readonly previewServerFactory;
     private readonly entryFile;
-    constructor({ appConfig, staticSiteGenerator, serveOptions, apiHandlers, logger, previewServerFactory, entryFile, }: ServerStaticBuilderParams);
-    private warnApiHandlersUnavailableInStaticMode;
+    private readonly hmrManager?;
+    private readonly onRuntimePlugin?;
+    constructor({ appConfig, staticSiteGenerator, serveOptions, runtimeOrigin, needsServerBundle, logger, entryFile, hmrManager, onRuntimePlugin, }: ServerStaticBuilderParams);
     private prepareExportDirectory;
     private refreshRuntimeAssets;
     /**
      * Bundles the server entry file for production use.
      *
      * @remarks
-     * When the project has API endpoints, the entry file must be bundled
-     * into a single JS file so the production server can start without
-     * on-the-fly TypeScript transpilation. The bundle is output to
-     * `dist/{SERVER_BUNDLE_DIR}/{SERVER_BUNDLE_FILENAME}` and used by
-     * `ecopages start` in production.
+     * Only invoked when the app requires a runtime server (API handlers,
+     * websocket handlers, etc.). Static-only apps skip this step entirely.
+     * Incremental builds may skip Rolldown when the `.eco/.server-entry`
+     * cache is still valid.
      *
      * Package imports remain external so native addons and runtime-owned
      * dependencies continue to load through the app's installed
      * `node_modules` tree. Only the app entry graph is bundled.
      *
-     * Skips silently when no API endpoints are registered (static-only site).
      * Throws if the build adapter is unavailable, is owned by a host
      * runtime, or bundling fails.
      *
@@ -81,7 +73,6 @@ export declare class ServerStaticBuilder {
     private bundleServerEntry;
     /**
      * Generates a static build of the site for deployment.
-     * @param options.preview - If true, starts a preview server after build
      * @param dependencies.router - The initialized router
      * @param dependencies.routeRendererFactory - The route renderer factory
      * @param dependencies.staticRoutes - Explicit static routes registered via app.static()