@harpy-js/core 0.5.2 → 0.5.4

package/dist/cli.js

@@ -8,11 +8,13 @@ const scripts = {
     "build-hydration": path.join(__dirname, "../scripts/build-hydration.ts"),
     "auto-wrap": path.join(__dirname, "../scripts/auto-wrap-exports.ts"),
     "build-styles": path.join(__dirname, "../scripts/build-page-styles.ts"),
+    build: path.join(__dirname, "../scripts/build.ts"),
+    start: path.join(__dirname, "../scripts/start.ts"),
     dev: path.join(__dirname, "../scripts/dev.ts"),
 };
 if (!command || !scripts[command]) {
     console.error("Usage: harpy <command>");
-    console.error("Commands: build-hydration, auto-wrap, build-styles, dev");
+    console.error("Commands: build, start, dev, build-hydration, auto-wrap, build-styles");
     process.exit(1);
 }
 const scriptPath = scripts[command];

package/dist/core/app-setup.d.ts

@@ -2,6 +2,7 @@ import type { NestFastifyApplication } from "@nestjs/platform-fastify";
 export interface HarpyAppOptions {
     layout?: any;
     distDir?: string;
+    publicDir?: string;
 }
 export declare function configureHarpyApp(app: NestFastifyApplication, opts?: HarpyAppOptions): Promise<void>;
 export declare function setupHarpyApp(app: NestFastifyApplication, opts?: HarpyAppOptions): Promise<void>;

package/dist/core/app-setup.js

@@ -52,7 +52,7 @@ catch (e) {
 }
 const jsx_engine_1 = require("./jsx.engine");
 async function configureHarpyApp(app, opts = {}) {
-    const { layout, distDir = "dist" } = opts;
+    const { layout, distDir = "dist", publicDir } = opts;
     if (layout) {
         (0, jsx_engine_1.withJsxEngine)(app, layout);
     }
@@ -69,6 +69,13 @@ async function configureHarpyApp(app, opts = {}) {
             prefix: "/",
             decorateReply: false,
         });
+        if (publicDir) {
+            await fastify.register(fastifyStatic, {
+                root: path.join(process.cwd(), publicDir),
+                prefix: "/",
+                decorateReply: false,
+            });
+        }
     }
     else {
         console.warn("[harpy-core] optional dependency `@fastify/static` is not installed; static `dist` handler not registered.");

package/dist/index.d.ts

@@ -19,3 +19,4 @@ export { configureHarpyApp, HarpyAppOptions } from "./core/app-setup";
 export { setupHarpyApp } from "./core/app-setup";
 export { default as Link } from "./client/Link";
 export { buildHrefIndex, getActiveItemIdFromIndex, getActiveItemIdFromManifest, } from "./client/getActiveItemId";
+export { useI18n } from "./client/use-i18n";

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getActiveItemIdFromManifest = exports.getActiveItemIdFromIndex = exports.buildHrefIndex = exports.Link = exports.setupHarpyApp = exports.configureHarpyApp = exports.AutoRegisterModule = exports.NavigationService = exports.RouterModule = exports.DefaultSeoService = exports.BaseSeoService = exports.SeoModule = exports.WithLayout = exports.JsxRender = exports.StaticAssetsController = exports.LiveReloadController = exports.withJsxEngine = exports.getHydrationManifest = exports.getChunkPath = exports.initializeHydrationContext = exports.hydrationContext = exports.autoWrapClientComponent = void 0;
+exports.useI18n = exports.getActiveItemIdFromManifest = exports.getActiveItemIdFromIndex = exports.buildHrefIndex = exports.Link = exports.setupHarpyApp = exports.configureHarpyApp = exports.AutoRegisterModule = exports.NavigationService = exports.RouterModule = exports.DefaultSeoService = exports.BaseSeoService = exports.SeoModule = exports.WithLayout = exports.JsxRender = exports.StaticAssetsController = exports.LiveReloadController = exports.withJsxEngine = exports.getHydrationManifest = exports.getChunkPath = exports.initializeHydrationContext = exports.hydrationContext = exports.autoWrapClientComponent = void 0;
 var client_component_wrapper_1 = require("./core/client-component-wrapper");
 Object.defineProperty(exports, "autoWrapClientComponent", { enumerable: true, get: function () { return client_component_wrapper_1.autoWrapClientComponent; } });
 var hydration_1 = require("./core/hydration");
@@ -42,3 +42,5 @@ var getActiveItemId_1 = require("./client/getActiveItemId");
 Object.defineProperty(exports, "buildHrefIndex", { enumerable: true, get: function () { return getActiveItemId_1.buildHrefIndex; } });
 Object.defineProperty(exports, "getActiveItemIdFromIndex", { enumerable: true, get: function () { return getActiveItemId_1.getActiveItemIdFromIndex; } });
 Object.defineProperty(exports, "getActiveItemIdFromManifest", { enumerable: true, get: function () { return getActiveItemId_1.getActiveItemIdFromManifest; } });
+var use_i18n_1 = require("./client/use-i18n");
+Object.defineProperty(exports, "useI18n", { enumerable: true, get: function () { return use_i18n_1.useI18n; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harpy-js/core",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Harpy - A powerful NestJS + React/JSX SSR framework with automatic hydration and i18n support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/auto-wrap-exports.ts

@@ -11,6 +11,9 @@
 
 import * as fs from "fs";
 import * as path from "path";
+import { Logger } from "./logger";
+
+const logger = new Logger("AutoWrapper");
 
 const PROJECT_ROOT = process.cwd();
 const SRC_DIR = path.join(PROJECT_ROOT, "src");
@@ -213,16 +216,16 @@ function transformCompiledFile(
  * Main function
  */
 function main(): void {
-  console.log("🔄 Auto-wrapping client component exports...\n");
+  logger.log("Auto-wrapping client component exports...");
 
   const clientComponents = findClientComponentsInSource();
 
   if (clientComponents.size === 0) {
-    console.log("⚠️  No client components found\n");
+    logger.warn("No client components found");
     return;
   }
 
-  console.log(`Found ${clientComponents.size} client component(s):\n`);
+  logger.log(`Found ${clientComponents.size} client component(s)`);
 
   let wrapped = 0;
   for (const [compiledPath, componentName] of clientComponents) {
@@ -231,9 +234,7 @@ function main(): void {
     }
   }
 
-  console.log(
-    `\n✨ Auto-wrap complete: ${wrapped}/${clientComponents.size} components wrapped\n`,
-  );
+  logger.log(`Auto-wrap complete: ${wrapped}/${clientComponents.size} components wrapped`);
 }
 
 main();

package/scripts/build-hydration.ts

@@ -13,6 +13,9 @@ import { execSync } from "child_process";
 import * as crypto from "crypto";
 import * as fs from "fs";
 import * as path from "path";
+import { Logger } from "./logger";
+
+const logger = new Logger("HydrationBuilder");
 
 const PROJECT_ROOT = process.cwd();
 const SRC_DIR = path.join(PROJECT_ROOT, "src");
@@ -181,11 +184,11 @@ function main(): void {
     fs.mkdirSync(HYDRATION_ENTRIES_DIR, { recursive: true });
   }
 
-  console.log("🔍 Detecting client components...");
+  logger.log("Detecting client components...");
   const clientComponents = findClientComponents();
 
   if (clientComponents.length === 0) {
-    console.log("⚠️  No client components found");
+    logger.warn("No client components found");
     // Still ensure chunks directory exists and clear manifest
     if (!fs.existsSync(CHUNKS_DIR)) {
       fs.mkdirSync(CHUNKS_DIR, { recursive: true });
@@ -207,7 +210,7 @@ function main(): void {
     fs.mkdirSync(CHUNKS_DIR, { recursive: true });
   }
 
-  console.log("\n📝 Generating hydration entries...");
+  logger.log("Generating hydration entries...");
 
   // Generate hydration entry files
   const entryFiles: { path: string; componentName: string }[] = [];
@@ -223,11 +226,10 @@ function main(): void {
       path: entryPath,
       componentName: component.componentName,
     });
-    console.log(`   ✓ ${component.componentName}.tsx`);
   }
 
   // Build shared vendor bundle first
-  console.log("\n📦 Building shared vendor bundle...");
+  logger.log("Building shared vendor bundle...");
   const vendorEntryPath = path.join(HYDRATION_ENTRIES_DIR, "_vendor.js");
   const vendorContent = `
 import React from 'react';
@@ -242,16 +244,15 @@ window.ReactDOM = ReactDOM;
 
   const vendorOutputPath = path.join(CHUNKS_DIR, VENDOR_BUNDLE);
   try {
-    const vendorCommand = `npx esbuild "${vendorEntryPath}" --bundle --minify --target=es2020 --format=iife --outfile="${vendorOutputPath}" --platform=browser --tree-shaking=true --define:process.env.NODE_ENV=\\"production\\"`;
+    const vendorCommand = `npx esbuild "${vendorEntryPath}" --bundle --minify --target=es2020 --format=iife --outfile="${vendorOutputPath}" --platform=browser --tree-shaking=true --define:process.env.NODE_ENV='"production"'`;
     execSync(vendorCommand, { stdio: "inherit" });
-    console.log(`   ✓ vendor.js (React + ReactDOM)`);
   } catch (error) {
-    console.error(`   ✗ Failed to bundle vendor:`, error);
+    logger.error(`Failed to bundle vendor: ${error}`);
     process.exit(1);
   }
 
   // Bundle each entry file separately with cache-busted names
-  console.log("\n📦 Bundling hydration scripts...");
+  logger.log("Bundling hydration scripts...");
 
   // Create React shim files for aliasing
   const SHIMS_DIR = path.join(DIST_DIR, ".shims");
@@ -301,27 +302,25 @@ module.exports = {
 
     try {
       // Use aliases to redirect React imports to window.React from vendor bundle
-      const command = `npx esbuild "${entry.path}" --bundle --minify --target=es2020 --format=iife --keep-names --outfile="${outputPath}" --platform=browser --tree-shaking=true --define:process.env.NODE_ENV=\\"production\\" --alias:react=${reactShimPath} --alias:react-dom=${reactDomShimPath} --alias:react-dom/client=${reactDomClientShimPath} --alias:react/jsx-runtime=${jsxRuntimeShimPath}`;
+      const command = `npx esbuild "${entry.path}" --bundle --minify --target=es2020 --format=iife --keep-names --outfile="${outputPath}" --platform=browser --tree-shaking=true --define:process.env.NODE_ENV='"production"' --alias:react=${reactShimPath} --alias:react-dom=${reactDomShimPath} --alias:react-dom/client=${reactDomClientShimPath} --alias:react/jsx-runtime=${jsxRuntimeShimPath}`;
       execSync(command, { stdio: "inherit" });
       manifest[entry.componentName] = chunkFilename;
-      console.log(`   ✓ ${entry.componentName} -> ${chunkFilename}`);
     } catch (error) {
-      console.error(`   ✗ Failed to bundle ${entry.componentName}:`, error);
+      logger.error(`Failed to bundle ${entry.componentName}: ${error}`);
       process.exit(1);
     }
   }
 
   // Write manifest file for server-side lookup
-  console.log("\n📋 Writing hydration manifest...");
+  logger.log("Writing hydration manifest...");
   fs.writeFileSync(MANIFEST_FILE, JSON.stringify(manifest, null, 2), "utf-8");
-  console.log(`   ✓ Manifest written to ${MANIFEST_FILE}`);
 
   // Clean up temporary entries directory
   if (fs.existsSync(HYDRATION_ENTRIES_DIR)) {
     fs.rmSync(HYDRATION_ENTRIES_DIR, { recursive: true });
   }
 
-  console.log("\n✨ Hydration build complete!");
+  logger.log("Hydration build complete!");
 }
 
 main();

package/scripts/build-page-styles.ts

@@ -7,7 +7,9 @@
 import { execSync } from "child_process";
 import * as fs from "fs";
 import * as path from "path";
+import { Logger } from "./logger";
 
+const logger = new Logger("StylesBuilder");
 const projectRoot = process.cwd();
 const distDir = path.join(projectRoot, "dist");
 const stylesDir = path.join(distDir, "styles");
@@ -15,7 +17,7 @@ const srcAssetsDir = path.join(projectRoot, "src/assets");
 const outputCssPath = path.join(stylesDir, "styles.css");
 
 async function main(): Promise<void> {
-  console.log("🎨 Building styles...");
+  logger.log("Building styles...");
 
   try {
     // Ensure styles directory exists
@@ -24,7 +26,7 @@ async function main(): Promise<void> {
     }
 
     // Compile Tailwind CSS
-    console.log("   Compiling Tailwind CSS...");
+    logger.log("Compiling Tailwind CSS...");
     execSync(
       `NODE_ENV=production postcss ${path.join(srcAssetsDir, "styles.css")} -o ${outputCssPath}`,
       {
@@ -32,10 +34,9 @@ async function main(): Promise<void> {
       },
     );
 
-    console.log(`   ✓ Generated styles.css`);
-    console.log("✨ Styles build complete!");
+    logger.log("Styles build complete!");
   } catch (error: any) {
-    console.error("❌ CSS generation failed:", error.message);
+    logger.error(`CSS generation failed: ${error.message}`);
     process.exit(1);
   }
 }

package/scripts/build.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import { spawn } from "child_process";
+import { Logger } from "./logger";
+
+const logger = new Logger("Builder");
+
+async function runCommand(cmd: string, args: string[] = []): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(cmd, args, { stdio: "inherit", shell: true });
+    proc.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`Command failed with code ${code}`));
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+async function buildNestApp(): Promise<void> {
+  logger.log("Building NestJS application...");
+  try {
+    await runCommand("nest", ["build"]);
+  } catch (error) {
+    logger.error(`NestJS build failed: ${error}`);
+    throw error;
+  }
+}
+
+async function buildHydration(): Promise<void> {
+  logger.log("Building hydration components...");
+  try {
+    const tsxPath = require("child_process")
+      .execSync("which tsx", { encoding: "utf-8" })
+      .trim();
+    await runCommand(tsxPath, [
+      require("path").join(__dirname, "build-hydration.ts"),
+    ]);
+  } catch (error) {
+    logger.error(`Hydration build failed: ${error}`);
+    throw error;
+  }
+}
+
+async function autoWrap(): Promise<void> {
+  logger.log("Auto-wrapping client components...");
+  try {
+    const tsxPath = require("child_process")
+      .execSync("which tsx", { encoding: "utf-8" })
+      .trim();
+    await runCommand(tsxPath, [
+      require("path").join(__dirname, "auto-wrap-exports.ts"),
+    ]);
+  } catch (error) {
+    logger.error(`Auto-wrap failed: ${error}`);
+    throw error;
+  }
+}
+
+async function buildStyles(): Promise<void> {
+  logger.log("Building styles...");
+  try {
+    const tsxPath = require("child_process")
+      .execSync("which tsx", { encoding: "utf-8" })
+      .trim();
+    await runCommand(tsxPath, [
+      require("path").join(__dirname, "build-page-styles.ts"),
+    ]);
+  } catch (error) {
+    logger.error(`Styles build failed: ${error}`);
+    throw error;
+  }
+}
+
+async function main(): Promise<void> {
+  try {
+    logger.log("Starting production build...");
+
+    await buildNestApp();
+    await buildHydration();
+    await autoWrap();
+    await buildStyles();
+
+    logger.log("Production build complete!");
+    process.exit(0);
+  } catch (error) {
+    logger.error(`Build failed: ${error}`);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/dev.ts

@@ -3,6 +3,9 @@
 import { spawn } from "child_process";
 import * as fs from "fs";
 import * as http from "http";
+import { Logger } from "./logger";
+
+const logger = new Logger("DevServer");
 
 let nestProcess: any = null;
 let isRebuilding = false;
@@ -43,43 +46,52 @@ async function runCommand(cmd: string, args: string[] = []): Promise<void> {
 }
 
 async function buildHydration(): Promise<void> {
-  console.log("🔧 Building hydration...");
+  logger.log("Building hydration components...");
   try {
-    await runCommand("pnpm", ["build:hydration"]);
-    console.log("✅ Hydration built");
+    const tsxPath = require("child_process")
+      .execSync("which tsx", { encoding: "utf-8" })
+      .trim();
+    await runCommand(tsxPath, [
+      require("path").join(__dirname, "build-hydration.ts"),
+    ]);
   } catch (error) {
-    console.error("❌ Hydration build failed:", error);
+    logger.error(`Hydration build failed: ${error}`);
     throw error;
   }
 }
 
 async function autoWrap(): Promise<void> {
-  console.log("🔄 Auto-wrapping client components...");
+  logger.log("Auto-wrapping client components...");
   try {
-    await runCommand("pnpm", ["auto-wrap"]);
-    console.log("✅ Auto-wrap complete");
+    const tsxPath = require("child_process")
+      .execSync("which tsx", { encoding: "utf-8" })
+      .trim();
+    await runCommand(tsxPath, [
+      require("path").join(__dirname, "auto-wrap-exports.ts"),
+    ]);
   } catch (error) {
-    console.error("❌ Auto-wrap failed:", error);
-    throw error;
+    logger.error(`Auto-wrap failed: ${error}`);
   }
 }
 
 async function buildStyles(): Promise<void> {
-  console.log("🎨 Building styles...");
+  logger.log("Building styles...");
   try {
-    await runCommand("pnpm", ["build:styles"]);
-    console.log("✅ Styles built");
+    const tsxPath = require("child_process")
+      .execSync("which tsx", { encoding: "utf-8" })
+      .trim();
+    await runCommand(tsxPath, [
+      require("path").join(__dirname, "build-page-styles.ts"),
+    ]);
   } catch (error) {
-    console.error("❌ Styles build failed:", error);
-    throw error;
+    logger.error(`Styles build failed: ${error}`);
   }
 }
 
 async function startNestServer(): Promise<void> {
   return new Promise((resolve) => {
-    console.log("🚀 Starting NestJS server from compiled dist...");
+    logger.log("Starting NestJS application...");
     // Run compiled dist/main.js instead of using ts-node
-    // This ensures auto-wrapped components are used
     nestProcess = spawn("node", ["--watch", "dist/main.js"], {
       stdio: "pipe",
       shell: false,
@@ -106,15 +118,14 @@ async function startNestServer(): Promise<void> {
           setTimeout(async () => {
             if (isRebuilding) return;
             isRebuilding = true;
-            console.log("\n🔄 NestJS rebuild detected, rebuilding assets...");
+            logger.log("Rebuilding assets after code change...");
             try {
               await buildHydration();
               await autoWrap();
               await buildStyles();
-              console.log("✅ Assets rebuilt\n");
               triggerBrowserReload();
             } catch (error) {
-              console.error("❌ Asset rebuild failed:", error);
+              logger.error(`Asset rebuild failed: ${error}`);
             } finally {
               isRebuilding = false;
             }
@@ -139,10 +150,9 @@ async function startNestServer(): Promise<void> {
 }
 
 function watchSourceChanges(): void {
-  console.log("👀 Watching source files for changes...");
+  logger.log("Watching source files for changes...");
 
   let debounceTimer: NodeJS.Timeout | null = null;
-  const watchedFiles = new Set<string>();
 
   // Watch src for CSS changes only (TS/TSX changes are handled by NestJS watch + stdout detection)
   fs.watch("src", { recursive: true }, async (eventType, filename) => {
@@ -168,14 +178,13 @@ function watchSourceChanges(): void {
 
     debounceTimer = setTimeout(async () => {
       isRebuilding = true;
-      console.log(`\n📝 CSS file changed: ${filename}`);
+      logger.log(`CSS file changed: ${filename}`);
 
       try {
         await buildStyles();
-        console.log("✅ Styles rebuilt\n");
         triggerBrowserReload();
       } catch (error) {
-        console.error("Build error:", error);
+        logger.error(`Style rebuild failed: ${error}`);
       } finally {
         watchedFiles.delete(filename);
         isRebuilding = false;
@@ -188,7 +197,7 @@ let tscProcess: any = null;
 
 async function startTypeScriptWatch(): Promise<void> {
   return new Promise((resolve) => {
-    console.log("⚙️  Starting TypeScript compiler in watch mode...");
+    logger.log("Starting TypeScript compiler in watch mode...");
     tscProcess = spawn("pnpm", ["nest", "build", "--watch"], {
       stdio: "pipe",
       shell: true,
@@ -215,13 +224,13 @@ async function startTypeScriptWatch(): Promise<void> {
 
 async function main(): Promise<void> {
   try {
-    console.log("📦 Initializing development environment...\n");
+    logger.log("Initializing development environment...");
 
     // First: Start TypeScript compiler in watch mode
     await startTypeScriptWatch();
 
     // Build initial assets after first compilation
-    console.log("\n🔧 Building hydration assets...");
+    logger.log("Building initial assets...");
     await buildHydration();
     await autoWrap();
     await buildStyles();
@@ -229,27 +238,27 @@ async function main(): Promise<void> {
     // Now start the node server with compiled dist files
     await startNestServer();
 
-    console.log("\n✅ Development server ready!\n");
+    logger.log("Development server ready!");
 
     // Watch for source changes
     watchSourceChanges();
 
     // Handle graceful shutdown
     process.on("SIGINT", async () => {
-      console.log("\n\n🛑 Stopping development server...");
+      logger.log("Stopping development server...");
       if (tscProcess) tscProcess.kill();
       if (nestProcess) nestProcess.kill();
       process.exit(0);
     });
 
     process.on("SIGTERM", async () => {
-      console.log("\n\n🛑 Stopping development server...");
+      logger.log("Stopping development server...");
       if (tscProcess) tscProcess.kill();
       if (nestProcess) nestProcess.kill();
       process.exit(0);
     });
   } catch (error) {
-    console.error("Fatal error:", error);
+    logger.error(`Fatal error: ${error}`);
     process.exit(1);
   }
 }

package/scripts/logger.ts

@@ -0,0 +1,53 @@
+/**
+ * Logger utility to format logs matching NestJS style
+ * Format: [Harpy] PID  - DATE, TIME     LEVEL [Context] Message +Xms
+ */
+
+const pid = process.pid;
+
+function getTimestamp(): string {
+  const now = new Date();
+  const date = now.toLocaleDateString("en-US");
+  const time = now.toLocaleTimeString("en-US");
+  return `${date}, ${time}`;
+}
+
+export class Logger {
+  private context: string;
+  private lastLogTime: number = Date.now();
+
+  constructor(context: string) {
+    this.context = context;
+  }
+
+  private formatMessage(level: string, message: string, levelColor: string): string {
+    const timestamp = getTimestamp();
+    const elapsed = Date.now() - this.lastLogTime;
+    this.lastLogTime = Date.now();
+    
+    const harpyPid = `\x1b[32m[Harpy] ${pid}\x1b[0m`;  // green
+    const timestampFormatted = `\x1b[37m${timestamp}\x1b[0m`;  // white
+    const levelColored = `\x1b[${levelColor}m${level.padEnd(5)}\x1b[0m`;
+    const contextColored = `\x1b[33m[${this.context}]\x1b[0m`;  // yellow
+    const messageColored = `\x1b[${levelColor}m${message}\x1b[0m`;
+    const elapsedColored = `\x1b[33m+${elapsed}ms\x1b[0m`;  // yellow
+    
+    return `${harpyPid}  - ${timestampFormatted}     ${levelColored} ${contextColored} ${messageColored} ${elapsedColored}`;
+  }
+
+  log(message: string): void {
+    console.log(this.formatMessage("LOG", message, "32")); // green
+  }
+
+  error(message: string): void {
+    console.error(this.formatMessage("ERROR", message, "31")); // red
+  }
+
+  warn(message: string): void {
+    console.warn(this.formatMessage("WARN", message, "33")); // yellow
+  }
+
+  verbose(message: string): void {
+    console.log(this.formatMessage("LOG", message, "36")); // cyan
+  }
+}

package/scripts/start.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { spawn } from "child_process";
+import { Logger } from "./logger";
+
+const logger = new Logger("Server");
+
+function startServer(): void {
+  logger.log("Starting production server...");
+
+  const serverProcess = spawn("node", ["dist/main.js"], {
+    stdio: "inherit",
+    shell: false,
+    cwd: process.cwd(),
+  });
+
+  serverProcess.on("error", (error) => {
+    logger.error(`Failed to start server: ${error.message}`);
+    process.exit(1);
+  });
+
+  serverProcess.on("exit", (code) => {
+    if (code !== 0) {
+      logger.error(`Server exited with code ${code}`);
+      process.exit(code || 1);
+    }
+  });
+
+  // Handle termination signals
+  process.on("SIGINT", () => {
+    logger.log("Shutting down server...");
+    serverProcess.kill("SIGINT");
+  });
+
+  process.on("SIGTERM", () => {
+    logger.log("Shutting down server...");
+    serverProcess.kill("SIGTERM");
+  });
+}
+
+startServer();

package/src/cli.ts

@@ -10,12 +10,14 @@ const scripts: Record<string, string> = {
   "build-hydration": path.join(__dirname, "../scripts/build-hydration.ts"),
   "auto-wrap": path.join(__dirname, "../scripts/auto-wrap-exports.ts"),
   "build-styles": path.join(__dirname, "../scripts/build-page-styles.ts"),
+  build: path.join(__dirname, "../scripts/build.ts"),
+  start: path.join(__dirname, "../scripts/start.ts"),
   dev: path.join(__dirname, "../scripts/dev.ts"),
 };
 
 if (!command || !scripts[command]) {
   console.error("Usage: harpy <command>");
-  console.error("Commands: build-hydration, auto-wrap, build-styles, dev");
+  console.error("Commands: build, start, dev, build-hydration, auto-wrap, build-styles");
   process.exit(1);
 }
 

package/src/core/app-setup.ts

@@ -28,6 +28,8 @@ export interface HarpyAppOptions {
   layout?: any;
   /** Folder containing built server assets (chunks) — defaults to `dist` */
   distDir?: string;
+  /** Optional folder containing public assets (favicon, manifest, etc.) */
+  publicDir?: string;
 }
 
 /**
@@ -43,7 +45,7 @@ export async function configureHarpyApp(
   app: NestFastifyApplication,
   opts: HarpyAppOptions = {},
 ) {
-  const { layout, distDir = "dist" } = opts;
+  const { layout, distDir = "dist", publicDir } = opts;
 
   if (layout) {
     withJsxEngine(app, layout);
@@ -79,6 +81,16 @@ export async function configureHarpyApp(
       prefix: "/",
       decorateReply: false,
     });
+
+    // If publicDir is provided, register it as well for public assets
+    if (publicDir) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      await fastify.register(fastifyStatic, {
+        root: path.join(process.cwd(), publicDir),
+        prefix: "/",
+        decorateReply: false,
+      });
+    }
   } else {
     // If the static plugin is not available, emit a warning and continue.
     // Consumers who need hydration chunk serving in production should add

package/src/index.ts

@@ -33,3 +33,4 @@ export {
   getActiveItemIdFromIndex,
   getActiveItemIdFromManifest,
 } from "./client/getActiveItemId";
+export { useI18n } from "./client/use-i18n";