heliumts 0.7.6 → 0.8.0

package/README.md

@@ -23,6 +23,7 @@ HeliumTS is a blazing fast 🚀 and opinionated full-stack React + Vite framewor
    - [Middleware](#35-middleware)
    - [Configuration](#36-heliumconfigts)
    - [Static Site Generation (SSG)](#37-static-site-generation-ssg)
+   - [Server-Side Rendering (SSR)](#38-server-side-rendering-ssr)
 4. [CLI Reference](#4-cli-reference)
 5. [More Documentation](#5-more-documentation)
 6. [Contributing](#6-contributing)
@@ -331,7 +332,55 @@ During build, Helium validates SSG pages and generates optimized static HTML fil
 
 See [SSG Documentation](./docs/ssg.md) for detailed information including limitations, hybrid rendering, and best practices.
 
-## 4.CLI Reference
+### 3.8. Server-Side Rendering (SSR)
+
+HeliumTS supports Server-Side Rendering (SSR) for pages that need fully rendered HTML on every request — useful for SEO, social media crawlers, and pages with per-request personalised data.
+
+Add a `"use ssr"` directive at the top of your page file to enable SSR:
+
+**SSR page: (`src/pages/dashboard.tsx`)**
+```tsx
+"use ssr";
+
+export default function DashboardPage({ user }: { user: string }) {
+    return <h1>Welcome, {user}</h1>;
+}
+```
+
+To fetch data on the server for each request, export a `getServerSideProps` function from the same file or a sidecar `page.server.ts` file (recommended):
+
+```ts
+// src/pages/dashboard.server.ts
+import type { GetServerSideProps } from "heliumts/server";
+
+export const getServerSideProps: GetServerSideProps = async (req, ctx) => {
+    const user = await getUser(req.headers);
+    return { user };
+};
+```
+
+Props are injected into the HTML as `window.__HELIUM_SSR_DATA__` and passed to the component. React hydrates the page client-side without a second server round-trip.
+
+**`isSSR()` utility** — use this in layouts to skip client-only guards (e.g. auth redirects) during server rendering while still providing required context providers:
+
+```tsx
+import { isSSR } from "heliumts/client";
+
+export default function AppLayout({ children }: { children: React.ReactNode }) {
+    const { isPending, data } = useSession();
+
+    if (!isSSR()) {
+        if (isPending) return null;
+        if (!data?.session) return null;
+    }
+
+    return <Providers>{children}</Providers>;
+}
+```
+
+See [SSR Documentation](./docs/ssr.md) for detailed information including sidecar files, layout guards, browser-only dependencies, and how hydration works.
+
+## 4. CLI Reference
 
 -   `helium dev`: Starts Vite in development mode.
 -   `helium build`:
@@ -351,6 +400,7 @@ See [SSG Documentation](./docs/ssg.md) for detailed information including limita
 -   [Routing & useRouter](./docs/routing.md) - File-based routing, dynamic routes, navigation, and the useRouter hook
 -   [Configuration](./docs/helium-config.md) - Configure RPC encoding, compression, security, and proxy settings
 -   [Static Site Generation](./docs/ssg.md) - Pre-render pages at build time for better performance
+-   [Server-Side Rendering](./docs/ssr.md) - Render pages on the server per-request for SEO and dynamic data
 -   [Route Groups](./docs/route-groups.md) - Organize routes with shared layouts without affecting URLs
 -   [Background Workers](./docs/workers.md) - Long-running background processes for queues, scheduled tasks, and more
 

package/dist/bin/helium.js

@@ -6,7 +6,7 @@ import fs from "fs";
 import path from "path";
 import { build as viteBuild } from "vite";
 import { log } from "../utils/logger.js";
-import { scanPageRoutePatterns, scanServerExports } from "../vite/scanner.js";
+import { scanAppShell, scanPageRoutePatterns, scanServerExports, scanSSRPages } from "../vite/scanner.js";
 import { generateStaticPages } from "../vite/ssg.js";
 import { generateServerManifest } from "../vite/virtualServerModule.js";
 const cli = cac("helium");
@@ -79,7 +79,9 @@ cli.command("build", "Build for production").action(async () => {
     // Generate server entry
     const serverExports = scanServerExports(root);
     const pageRoutePatterns = scanPageRoutePatterns(root);
-    const manifestCode = generateServerManifest(serverExports.methods, serverExports.httpHandlers, serverExports.seoMetadata, pageRoutePatterns, serverExports.middleware, serverExports.workers);
+    const ssrPages = scanSSRPages(root);
+    const appShell = scanAppShell(root);
+    const manifestCode = generateServerManifest(serverExports.methods, serverExports.httpHandlers, serverExports.seoMetadata, pageRoutePatterns, ssrPages, appShell, serverExports.middleware, serverExports.workers);
     // Create the main server module that will be imported after env is loaded
     const serverModuleCode = `
 import { startProdServer, loadConfig } from 'heliumts/server';
@@ -100,6 +102,8 @@ export async function start() {
                 httpRouter.setMiddleware(middlewareHandler);
             }
         },
+        ssrPages,
+        appShell,
         workers
     });
 }
@@ -131,9 +135,122 @@ if (Object.keys(envVars).length > 0) {
     const entryPath = path.join(heliumDir, "server-entry.ts");
     const envLoaderPath = path.join(heliumDir, "env-loader.ts");
     const serverModuleSrcPath = path.join(heliumDir, "server-module.ts");
+    const ssrClientStubPath = path.join(heliumDir, "ssr-client-stub.ts");
+    const ssrTransitionsStubPath = path.join(heliumDir, "ssr-transitions-stub.ts");
+    const ssrPrefetchStubPath = path.join(heliumDir, "ssr-prefetch-stub.ts");
+    const ssrClientStubCode = `
+import React from 'react';
+
+export const RouterContext = React.createContext(null);
+
+function getSSRRouterSnapshot() {
+    const snapshot = globalThis.__HELIUM_SSR_ROUTER__ as
+        | { path?: string; params?: Record<string, string | string[]>; search?: string }
+        | undefined;
+
+    if (!snapshot || typeof snapshot !== 'object') {
+        return {
+            path: '/',
+            params: {},
+            search: '',
+        };
+    }
+
+    return {
+        path: typeof snapshot.path === 'string' ? snapshot.path : '/',
+        params: snapshot.params && typeof snapshot.params === 'object' ? snapshot.params : {},
+        search: typeof snapshot.search === 'string' ? snapshot.search : '',
+    };
+}
+
+export function useRouter() {
+    const snapshot = getSSRRouterSnapshot();
+    return {
+        path: snapshot.path,
+        params: snapshot.params,
+        searchParams: new URLSearchParams(snapshot.search),
+        push: () => {},
+        replace: () => {},
+        on: () => () => {},
+        status: 200,
+        isNavigating: false,
+        isPending: false,
+    };
+}
+
+export function Link(props: { href?: string; children?: React.ReactNode } & Record<string, unknown>) {
+    const { href = '#', children, ...rest } = props || {};
+    return React.createElement('a', { href, ...rest }, children);
+}
+
+export function Redirect() {
+    return null;
+}
+
+export function AppRouter() {
+    return null;
+}
+
+export function useCall() {
+    return {
+        call: async () => null,
+        isCalling: false,
+        error: null,
+    };
+}
+
+export function useFetch() {
+    return {
+        data: null,
+        isLoading: false,
+        error: null,
+        refetch: async () => undefined,
+    };
+}
+
+export class RpcError extends Error {}
+
+export function getRpcTransport() {
+    return 'websocket';
+}
+
+export function isAutoHttpOnMobileEnabled() {
+    return false;
+}
+
+export function preconnect() {}
+
+export function isSSR() {
+    return true;
+}
+`;
+    const ssrTransitionsStubCode = `
+import React from 'react';
+
+export function useDeferredNavigation() {
+    return {
+        path: '/',
+        deferredPath: '/',
+        isStale: false,
+        isPending: false,
+        isTransitioning: false,
+    };
+}
+
+export function PageTransition({ children }: { children?: React.ReactNode }) {
+    return React.createElement(React.Fragment, null, children);
+}
+`;
+    const ssrPrefetchStubCode = `
+export function prefetchRoute() {}
+export function clearPrefetchCache() {}
+`;
     fs.writeFileSync(entryPath, entryCode);
     fs.writeFileSync(envLoaderPath, envLoaderCode);
     fs.writeFileSync(serverModuleSrcPath, serverModuleCode);
+    fs.writeFileSync(ssrClientStubPath, ssrClientStubCode);
+    fs.writeFileSync(ssrTransitionsStubPath, ssrTransitionsStubCode);
+    fs.writeFileSync(ssrPrefetchStubPath, ssrPrefetchStubCode);
     // Bundle with esbuild
     try {
         await esbuild({
@@ -142,6 +259,18 @@ if (Object.keys(envVars).length > 0) {
             bundle: true,
             platform: "node",
             format: "esm",
+            jsx: "automatic",
+            jsxImportSource: "react",
+            plugins: [
+                {
+                    name: "helium-ssr-client-alias",
+                    setup(build) {
+                        build.onResolve({ filter: /^heliumts\/client$/ }, () => ({ path: ssrClientStubPath }));
+                        build.onResolve({ filter: /^heliumts\/client\/transitions$/ }, () => ({ path: ssrTransitionsStubPath }));
+                        build.onResolve({ filter: /^heliumts\/client\/prefetch$/ }, () => ({ path: ssrPrefetchStubPath }));
+                    },
+                },
+            ],
             external: [
                 // External common database and heavy dependencies
                 "mongodb",

package/dist/bin/helium.js.map

@@ -1 +1 @@
-{"version":3,"file":"helium.js","sourceRoot":"","sources":["../../src/bin/helium.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAC1B,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,KAAK,IAAI,OAAO,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC1B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;AAE3B,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,0BAA0B,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;IAC7D,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;QACtB,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC;AAEH,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;IAC3D,GAAG,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAC;IAChD,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAElC,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC;YAC3B,IAAI;YACJ,QAAQ,EAAE,QAAQ;YAClB,KAAK,EAAE;gBACH,MAAM,EAAE,MAAM;aACjB;SACJ,CAAC,CAAC;QAEH,uBAAuB;QACvB,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,EAAE,CAAC;YAC/B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;YAC9B,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;YAElC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC1B,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;oBACnD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;oBAChC,MAAM,OAAO,GAAG,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;oBAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;oBACjD,MAAM,MAAM,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;oBAExC,yBAAyB;oBACzB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;oBACvC,MAAM,UAAU,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;oBAEtD,GAAG,CAAC,MAAM,EAAE,KAAK,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;gBAC1G,CAAC;YACL,CAAC;QACL,CAAC;QAED,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;QAEtC,gCAAgC;QAChC,GAAG,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAC;QAChD,IAAI,CAAC;YACD,sDAAsD;YACtD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YAElD,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC1B,IAAI,YAAY,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAEtD,iCAAiC;gBACjC,6EAA6E;gBAC7E,YAAY,GAAG,YAAY,CAAC,OAAO,CAAC,gFAAgF,EAAE,EAAE,CAAC,CAAC;gBAE1H,2DAA2D;gBAC3D,YAAY,GAAG,YAAY,CAAC,OAAO,CAAC,mCAAmC,EAAE,uBAAuB,CAAC,CAAC;gBAElG,MAAM,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;YACjE,CAAC;iBAAM,CAAC;gBACJ,GAAG,CAAC,MAAM,EAAE,4CAA4C,CAAC,CAAC;YAC9D,CAAC;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,GAAG,CAAC,MAAM,EAAE,wBAAwB,EAAE,CAAC,CAAC,CAAC;YACzC,oCAAoC;QACxC,CAAC;QACD,GAAG,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,GAAG,CAAC,OAAO,EAAE,sBAAsB,EAAE,CAAC,CAAC,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAClC,wBAAwB;IACxB,MAAM,aAAa,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,iBAAiB,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,sBAAsB,CACvC,aAAa,CAAC,OAAO,EACrB,aAAa,CAAC,YAAY,EAC1B,aAAa,CAAC,WAAW,EACzB,iBAAiB,EACjB,aAAa,CAAC,UAAU,EACxB,aAAa,CAAC,OAAO,CACxB,CAAC;IAEF,0EAA0E;IAC1E,MAAM,gBAAgB,GAAG;;EAE3B,YAAY;;;;;;;;;;;;;;;;;;;;CAoBb,CAAC;IAEE,+EAA+E;IAC/E,MAAM,SAAS,GAAG;;;;;;CAMrB,CAAC;IAEE,MAAM,aAAa,GAAG;;;;;;;;;;;CAWzB,CAAC;IAEE,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,WAAW,CAAC,CAAC;IAC/D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IAC5D,MAAM,mBAAmB,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;IAErE,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IACvC,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IAC/C,EAAE,CAAC,aAAa,CAAC,mBAAmB,EAAE,gBAAgB,CAAC,CAAC;IAExD,sBAAsB;IACtB,IAAI,CAAC;QACD,MAAM,OAAO,CAAC;YACV,WAAW,EAAE,CAAC,SAAS,CAAC;YACxB,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC;YAC7C,MAAM,EAAE,IAAI;YACZ,QAAQ,EAAE,MAAM;YAChB,MAAM,EAAE,KAAK;YACb,QAAQ,EAAE;gBACN,kDAAkD;gBAClD,SAAS;gBACT,UAAU;gBACV,IAAI;gBACJ,OAAO;gBACP,QAAQ;gBACR,SAAS;gBACT,gBAAgB;gBAChB,OAAO;gBACP,sEAAsE;gBACtE,QAAQ;gBACR,IAAI;gBACJ,MAAM;gBACN,MAAM;gBACN,OAAO;gBACP,QAAQ;gBACR,MAAM;gBACN,MAAM;aACT;YACD,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE;gBACJ,EAAE,EAAE,yFAAyF;aAChG;SACJ,CAAC,CAAC;QAEH,8BAA8B;QAC9B,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;QACnF,MAAM,WAAW,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;QACtE,MAAM,YAAY,GAAG,CAAC,WAAW,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC1D,GAAG,CAAC,MAAM,EAAE,KAAK,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAE/E,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;QAEtC,8DAA8D;QAC9D,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;QACzD,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YAC9B,GAAG,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAAC;YAC/C,IAAI,CAAC;gBACD,MAAM,OAAO,CAAC;oBACV,WAAW,EAAE,CAAC,YAAY,CAAC;oBAC3B,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,kBAAkB,CAAC;oBACpD,MAAM,EAAE,KAAK;oBACb,QAAQ,EAAE,MAAM;oBAChB,MAAM,EAAE,KAAK;oBACb,MAAM,EAAE,QAAQ;iBACnB,CAAC,CAAC;gBACH,GAAG,CAAC,MAAM,EAAE,iDAAiD,CAAC,CAAC;YACnE,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACT,GAAG,CAAC,MAAM,EAAE,kCAAkC,EAAE,CAAC,CAAC,CAAC;gBACnD,GAAG,CAAC,MAAM,EAAE,sEAAsE,CAAC,CAAC;YACxF,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,yDAAyD;YACzD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;YACzD,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;YAE3D,IAAI,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC9B,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;gBAC3E,GAAG,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAC;YACpD,CAAC;iBAAM,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;gBACtC,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;gBAC7E,GAAG,CAAC,MAAM,EAAE,mCAAmC,CAAC,CAAC;YACrD,CAAC;QACL,CAAC;QAED,GAAG,CAAC,MAAM,EAAE,kCAAkC,CAAC,CAAC;QAChD,GAAG,CAAC,MAAM,EAAE,gCAAgC,CAAC,CAAC;QAC9C,GAAG,CAAC,MAAM,EAAE,sDAAsD,CAAC,CAAC;QAEpE,qCAAqC;QACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACT,GAAG,CAAC,OAAO,EAAE,sBAAsB,EAAE,CAAC,CAAC,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,yBAAyB,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;IAC9D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IACxD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,OAAO,EAAE,mDAAmD,CAAC,CAAC;QAClE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;IAED,sEAAsE;IACtE,gDAAgD;IAChD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,EAAE;QACvC,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,IAAI;QACX,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,iBAAiB,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE;KACtE,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;QACxB,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC;AAEH,GAAG,CAAC,IAAI,EAAE,CAAC;AACX,GAAG,CAAC,KAAK,EAAE,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { cac } from \"cac\";\nimport { spawn } from \"child_process\";\nimport { build as esbuild } from \"esbuild\";\nimport fs from \"fs\";\nimport path from \"path\";\nimport { build as viteBuild } from \"vite\";\n\nimport { log } from \"../utils/logger.js\";\nimport { scanPageRoutePatterns, scanServerExports } from \"../vite/scanner.js\";\nimport { generateStaticPages } from \"../vite/ssg.js\";\nimport { generateServerManifest } from \"../vite/virtualServerModule.js\";\n\nconst cli = cac(\"helium\");\nconst root = process.cwd();\n\ncli.command(\"dev\", \"Start development server\").action(async () => {\n    const vite = spawn(\"vite\", [], { stdio: \"inherit\", shell: true });\n    vite.on(\"close\", (code) => {\n        process.exit(code || 0);\n    });\n});\n\ncli.command(\"build\", \"Build for production\").action(async () => {\n    log(\"info\", \"--------------------------------\");\n    log(\"info\", \"Building client...\");\n\n    try {\n        const result = await viteBuild({\n            root,\n            logLevel: \"silent\",\n            build: {\n                outDir: \"dist\",\n            },\n        });\n\n        // Display build output\n        if (result && \"output\" in result) {\n            const outputs = result.output;\n            const zlib = await import(\"zlib\");\n\n            for (const chunk of outputs) {\n                if (chunk.type === \"asset\" || chunk.type === \"chunk\") {\n                    const fileName = chunk.fileName;\n                    const content = \"code\" in chunk ? chunk.code : chunk.source;\n                    const size = Buffer.byteLength(content, \"utf-8\");\n                    const sizeKB = (size / 1024).toFixed(2);\n\n                    // Calculate gzipped size\n                    const gzipped = zlib.gzipSync(content);\n                    const gzipSizeKB = (gzipped.length / 1024).toFixed(2);\n\n                    log(\"info\", `  ${fileName.padEnd(35)} ${sizeKB.padStart(8)} kB │ gzip: ${gzipSizeKB.padStart(7)} kB`);\n                }\n            }\n        }\n\n        log(\"info\", \"Client build complete.\");\n\n        // Generate static pages for SSG\n        log(\"info\", \"--------------------------------\");\n        try {\n            // Read the generated index.html as a template for SSG\n            const distDir = path.join(root, \"dist\");\n            const htmlPath = path.join(distDir, \"index.html\");\n\n            if (fs.existsSync(htmlPath)) {\n                let htmlTemplate = fs.readFileSync(htmlPath, \"utf-8\");\n\n                // Clean up the template for SSG:\n                // 1. Remove the build-time HELIUM_CONNECTION_TOKEN (SSG pages don't need it)\n                htmlTemplate = htmlTemplate.replace(/<script>window\\.HELIUM_CONNECTION_TOKEN = \"build-time-placeholder\";<\\/script>/g, \"\");\n\n                // 2. Clear any existing content in root div from SPA build\n                htmlTemplate = htmlTemplate.replace(/<div\\s+id=\"root\"[^>]*>.*?<\\/div>/s, '<div id=\"root\"></div>');\n\n                await generateStaticPages(null, root, htmlTemplate, distDir);\n            } else {\n                log(\"warn\", \"index.html not found in dist, skipping SSG\");\n            }\n        } catch (e) {\n            log(\"warn\", \"SSG generation failed:\", e);\n            // Don't fail the build if SSG fails\n        }\n        log(\"info\", \"--------------------------------\");\n    } catch (e) {\n        log(\"error\", \"Client build failed:\", e);\n        process.exit(1);\n    }\n\n    log(\"info\", \"Building server...\");\n    // Generate server entry\n    const serverExports = scanServerExports(root);\n    const pageRoutePatterns = scanPageRoutePatterns(root);\n    const manifestCode = generateServerManifest(\n        serverExports.methods,\n        serverExports.httpHandlers,\n        serverExports.seoMetadata,\n        pageRoutePatterns,\n        serverExports.middleware,\n        serverExports.workers\n    );\n\n    // Create the main server module that will be imported after env is loaded\n    const serverModuleCode = `\nimport { startProdServer, loadConfig } from 'heliumts/server';\n${manifestCode}\n\nexport async function start() {\n    const config = await loadConfig();\n\n    startProdServer({\n        config,\n        registerHandlers: (registry, httpRouter, seoRouter) => {\n            registerAll(registry);\n            httpRouter.registerRoutes(httpHandlers);\n            seoRouter.registerRoutes(seoMetadataHandlers);\n            seoRouter.setPageRoutePatterns(pageRoutePatterns);\n            if (middlewareHandler) {\n                registry.setMiddleware(middlewareHandler);\n                httpRouter.setMiddleware(middlewareHandler);\n            }\n        },\n        workers\n    });\n}\n`;\n\n    // Create the entry loader that loads env first, then imports the server module\n    const entryCode = `\n// Load environment variables FIRST, before any other imports\nimport './env-loader.js';\n// Now import and start the server (this ensures handlers load after env)\nimport { start } from './server-module.js';\nawait start();\n`;\n\n    const envLoaderCode = `\nimport { loadEnvFiles, injectEnvToProcess, log } from 'heliumts/server';\nconst envRoot = process.cwd();\nlog('info', \\`Loading .env files from: \\${envRoot}\\`);\nconst envVars = loadEnvFiles({ mode: 'production' });\ninjectEnvToProcess(envVars);\nif (Object.keys(envVars).length > 0) {\n    log('info', \\`Loaded \\${Object.keys(envVars).length} environment variable(s) from .env files\\`);\n} else {\n    log('info', 'No .env files found (using platform environment variables if available)');\n}\n`;\n\n    const heliumDir = path.join(root, \"node_modules\", \".heliumts\");\n    if (!fs.existsSync(heliumDir)) {\n        fs.mkdirSync(heliumDir, { recursive: true });\n    }\n    const entryPath = path.join(heliumDir, \"server-entry.ts\");\n    const envLoaderPath = path.join(heliumDir, \"env-loader.ts\");\n    const serverModuleSrcPath = path.join(heliumDir, \"server-module.ts\");\n\n    fs.writeFileSync(entryPath, entryCode);\n    fs.writeFileSync(envLoaderPath, envLoaderCode);\n    fs.writeFileSync(serverModuleSrcPath, serverModuleCode);\n\n    // Bundle with esbuild\n    try {\n        await esbuild({\n            entryPoints: [entryPath],\n            outfile: path.join(root, \"dist\", \"server.js\"),\n            bundle: true,\n            platform: \"node\",\n            format: \"esm\",\n            external: [\n                // External common database and heavy dependencies\n                \"mongodb\",\n                \"mongoose\",\n                \"pg\",\n                \"mysql\",\n                \"mysql2\",\n                \"sqlite3\",\n                \"better-sqlite3\",\n                \"redis\",\n                // Node.js built-ins are automatically external, but let's be explicit\n                \"crypto\",\n                \"fs\",\n                \"path\",\n                \"http\",\n                \"https\",\n                \"stream\",\n                \"zlib\",\n                \"util\",\n            ],\n            target: \"node18\",\n            metafile: true,\n            banner: {\n                js: \"import { createRequire } from 'module'; const require = createRequire(import.meta.url);\",\n            },\n        });\n\n        // Display server build output\n        const serverOutputPath = path.relative(root, path.join(root, \"dist\", \"server.js\"));\n        const serverStats = fs.statSync(path.join(root, \"dist\", \"server.js\"));\n        const serverSizeKB = (serverStats.size / 1024).toFixed(2);\n        log(\"info\", `  ${serverOutputPath.padEnd(35)} ${serverSizeKB.padStart(8)} kB`);\n\n        log(\"info\", \"Server build complete.\");\n\n        // Transpile helium.config.ts to helium.config.js if it exists\n        const configTsPath = path.join(root, \"helium.config.ts\");\n        if (fs.existsSync(configTsPath)) {\n            log(\"info\", \"Transpiling helium.config.ts...\");\n            try {\n                await esbuild({\n                    entryPoints: [configTsPath],\n                    outfile: path.join(root, \"dist\", \"helium.config.js\"),\n                    bundle: false,\n                    platform: \"node\",\n                    format: \"esm\",\n                    target: \"node18\",\n                });\n                log(\"info\", \"Config file transpiled to dist/helium.config.js\");\n            } catch (e) {\n                log(\"warn\", \"Failed to transpile config file:\", e);\n                log(\"warn\", \"You may need to manually rename helium.config.ts to helium.config.js\");\n            }\n        } else {\n            // Check if .js or .mjs config exists and copy it to dist\n            const configJsPath = path.join(root, \"helium.config.js\");\n            const configMjsPath = path.join(root, \"helium.config.mjs\");\n\n            if (fs.existsSync(configJsPath)) {\n                fs.copyFileSync(configJsPath, path.join(root, \"dist\", \"helium.config.js\"));\n                log(\"info\", \"Copied helium.config.js to dist/\");\n            } else if (fs.existsSync(configMjsPath)) {\n                fs.copyFileSync(configMjsPath, path.join(root, \"dist\", \"helium.config.mjs\"));\n                log(\"info\", \"Copied helium.config.mjs to dist/\");\n            }\n        }\n\n        log(\"info\", \"--------------------------------\");\n        log(\"info\", \"✓ Build finished successfully.\");\n        log(\"info\", \"▶ Run 'helium start' to start the production server.\");\n\n        // Exit cleanly after build completes\n        process.exit(0);\n    } catch (e) {\n        log(\"error\", \"Server build failed:\", e);\n        process.exit(1);\n    }\n});\n\ncli.command(\"start\", \"Start production server\").action(async () => {\n    const serverPath = path.join(root, \"dist\", \"server.js\");\n    if (!fs.existsSync(serverPath)) {\n        log(\"error\", 'Server build not found. Run \"helium build\" first.');\n        process.exit(1);\n    }\n\n    // When running in production, look for config in dist directory first\n    // This allows the transpiled config to be found\n    const server = spawn(\"node\", [serverPath], {\n        stdio: \"inherit\",\n        shell: true,\n        env: { ...process.env, HELIUM_CONFIG_DIR: path.join(root, \"dist\") },\n    });\n    server.on(\"close\", (code) => {\n        process.exit(code || 0);\n    });\n});\n\ncli.help();\ncli.parse();\n"]}
+{"version":3,"file":"helium.js","sourceRoot":"","sources":["../../src/bin/helium.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\nimport { cac } from \"cac\";\nimport { spawn } from \"child_process\";\nimport { build as esbuild } from \"esbuild\";\nimport fs from \"fs\";\nimport path from \"path\";\nimport { build as viteBuild } from \"vite\";\n\nimport { log } from \"../utils/logger.js\";\nimport { scanAppShell, scanPageRoutePatterns, scanServerExports, scanSSRPages } from \"../vite/scanner.js\";\nimport { generateStaticPages } from \"../vite/ssg.js\";\nimport { generateServerManifest } from \"../vite/virtualServerModule.js\";\n\nconst cli = cac(\"helium\");\nconst root = process.cwd();\n\ncli.command(\"dev\", \"Start development server\").action(async () => {\n    const vite = spawn(\"vite\", [], { stdio: \"inherit\", shell: true });\n    vite.on(\"close\", (code) => {\n        process.exit(code || 0);\n    });\n});\n\ncli.command(\"build\", \"Build for production\").action(async () => {\n    log(\"info\", \"--------------------------------\");\n    log(\"info\", \"Building client...\");\n\n    try {\n        const result = await viteBuild({\n            root,\n            logLevel: \"silent\",\n            build: {\n                outDir: \"dist\",\n            },\n        });\n\n        // Display build output\n        if (result && \"output\" in result) {\n            const outputs = result.output;\n            const zlib = await import(\"zlib\");\n\n            for (const chunk of outputs) {\n                if (chunk.type === \"asset\" || chunk.type === \"chunk\") {\n                    const fileName = chunk.fileName;\n                    const content = \"code\" in chunk ? chunk.code : chunk.source;\n                    const size = Buffer.byteLength(content, \"utf-8\");\n                    const sizeKB = (size / 1024).toFixed(2);\n\n                    // Calculate gzipped size\n                    const gzipped = zlib.gzipSync(content);\n                    const gzipSizeKB = (gzipped.length / 1024).toFixed(2);\n\n                    log(\"info\", `  ${fileName.padEnd(35)} ${sizeKB.padStart(8)} kB │ gzip: ${gzipSizeKB.padStart(7)} kB`);\n                }\n            }\n        }\n\n        log(\"info\", \"Client build complete.\");\n\n        // Generate static pages for SSG\n        log(\"info\", \"--------------------------------\");\n        try {\n            // Read the generated index.html as a template for SSG\n            const distDir = path.join(root, \"dist\");\n            const htmlPath = path.join(distDir, \"index.html\");\n\n            if (fs.existsSync(htmlPath)) {\n                let htmlTemplate = fs.readFileSync(htmlPath, \"utf-8\");\n\n                // Clean up the template for SSG:\n                // 1. Remove the build-time HELIUM_CONNECTION_TOKEN (SSG pages don't need it)\n                htmlTemplate = htmlTemplate.replace(/<script>window\\.HELIUM_CONNECTION_TOKEN = \"build-time-placeholder\";<\\/script>/g, \"\");\n\n                // 2. Clear any existing content in root div from SPA build\n                htmlTemplate = htmlTemplate.replace(/<div\\s+id=\"root\"[^>]*>.*?<\\/div>/s, '<div id=\"root\"></div>');\n\n                await generateStaticPages(null, root, htmlTemplate, distDir);\n            } else {\n                log(\"warn\", \"index.html not found in dist, skipping SSG\");\n            }\n        } catch (e) {\n            log(\"warn\", \"SSG generation failed:\", e);\n            // Don't fail the build if SSG fails\n        }\n        log(\"info\", \"--------------------------------\");\n    } catch (e) {\n        log(\"error\", \"Client build failed:\", e);\n        process.exit(1);\n    }\n\n    log(\"info\", \"Building server...\");\n    // Generate server entry\n    const serverExports = scanServerExports(root);\n    const pageRoutePatterns = scanPageRoutePatterns(root);\n    const ssrPages = scanSSRPages(root);\n    const appShell = scanAppShell(root);\n    const manifestCode = generateServerManifest(\n        serverExports.methods,\n        serverExports.httpHandlers,\n        serverExports.seoMetadata,\n        pageRoutePatterns,\n        ssrPages,\n        appShell,\n        serverExports.middleware,\n        serverExports.workers\n    );\n\n    // Create the main server module that will be imported after env is loaded\n    const serverModuleCode = `\nimport { startProdServer, loadConfig } from 'heliumts/server';\n${manifestCode}\n\nexport async function start() {\n    const config = await loadConfig();\n\n    startProdServer({\n        config,\n        registerHandlers: (registry, httpRouter, seoRouter) => {\n            registerAll(registry);\n            httpRouter.registerRoutes(httpHandlers);\n            seoRouter.registerRoutes(seoMetadataHandlers);\n            seoRouter.setPageRoutePatterns(pageRoutePatterns);\n            if (middlewareHandler) {\n                registry.setMiddleware(middlewareHandler);\n                httpRouter.setMiddleware(middlewareHandler);\n            }\n        },\n        ssrPages,\n        appShell,\n        workers\n    });\n}\n`;\n\n    // Create the entry loader that loads env first, then imports the server module\n    const entryCode = `\n// Load environment variables FIRST, before any other imports\nimport './env-loader.js';\n// Now import and start the server (this ensures handlers load after env)\nimport { start } from './server-module.js';\nawait start();\n`;\n\n    const envLoaderCode = `\nimport { loadEnvFiles, injectEnvToProcess, log } from 'heliumts/server';\nconst envRoot = process.cwd();\nlog('info', \\`Loading .env files from: \\${envRoot}\\`);\nconst envVars = loadEnvFiles({ mode: 'production' });\ninjectEnvToProcess(envVars);\nif (Object.keys(envVars).length > 0) {\n    log('info', \\`Loaded \\${Object.keys(envVars).length} environment variable(s) from .env files\\`);\n} else {\n    log('info', 'No .env files found (using platform environment variables if available)');\n}\n`;\n\n    const heliumDir = path.join(root, \"node_modules\", \".heliumts\");\n    if (!fs.existsSync(heliumDir)) {\n        fs.mkdirSync(heliumDir, { recursive: true });\n    }\n    const entryPath = path.join(heliumDir, \"server-entry.ts\");\n    const envLoaderPath = path.join(heliumDir, \"env-loader.ts\");\n    const serverModuleSrcPath = path.join(heliumDir, \"server-module.ts\");\n    const ssrClientStubPath = path.join(heliumDir, \"ssr-client-stub.ts\");\n    const ssrTransitionsStubPath = path.join(heliumDir, \"ssr-transitions-stub.ts\");\n    const ssrPrefetchStubPath = path.join(heliumDir, \"ssr-prefetch-stub.ts\");\n\n    const ssrClientStubCode = `\nimport React from 'react';\n\nexport const RouterContext = React.createContext(null);\n\nfunction getSSRRouterSnapshot() {\n    const snapshot = globalThis.__HELIUM_SSR_ROUTER__ as\n        | { path?: string; params?: Record<string, string | string[]>; search?: string }\n        | undefined;\n\n    if (!snapshot || typeof snapshot !== 'object') {\n        return {\n            path: '/',\n            params: {},\n            search: '',\n        };\n    }\n\n    return {\n        path: typeof snapshot.path === 'string' ? snapshot.path : '/',\n        params: snapshot.params && typeof snapshot.params === 'object' ? snapshot.params : {},\n        search: typeof snapshot.search === 'string' ? snapshot.search : '',\n    };\n}\n\nexport function useRouter() {\n    const snapshot = getSSRRouterSnapshot();\n    return {\n        path: snapshot.path,\n        params: snapshot.params,\n        searchParams: new URLSearchParams(snapshot.search),\n        push: () => {},\n        replace: () => {},\n        on: () => () => {},\n        status: 200,\n        isNavigating: false,\n        isPending: false,\n    };\n}\n\nexport function Link(props: { href?: string; children?: React.ReactNode } & Record<string, unknown>) {\n    const { href = '#', children, ...rest } = props || {};\n    return React.createElement('a', { href, ...rest }, children);\n}\n\nexport function Redirect() {\n    return null;\n}\n\nexport function AppRouter() {\n    return null;\n}\n\nexport function useCall() {\n    return {\n        call: async () => null,\n        isCalling: false,\n        error: null,\n    };\n}\n\nexport function useFetch() {\n    return {\n        data: null,\n        isLoading: false,\n        error: null,\n        refetch: async () => undefined,\n    };\n}\n\nexport class RpcError extends Error {}\n\nexport function getRpcTransport() {\n    return 'websocket';\n}\n\nexport function isAutoHttpOnMobileEnabled() {\n    return false;\n}\n\nexport function preconnect() {}\n\nexport function isSSR() {\n    return true;\n}\n`;\n\n    const ssrTransitionsStubCode = `\nimport React from 'react';\n\nexport function useDeferredNavigation() {\n    return {\n        path: '/',\n        deferredPath: '/',\n        isStale: false,\n        isPending: false,\n        isTransitioning: false,\n    };\n}\n\nexport function PageTransition({ children }: { children?: React.ReactNode }) {\n    return React.createElement(React.Fragment, null, children);\n}\n`;\n\n    const ssrPrefetchStubCode = `\nexport function prefetchRoute() {}\nexport function clearPrefetchCache() {}\n`;\n\n    fs.writeFileSync(entryPath, entryCode);\n    fs.writeFileSync(envLoaderPath, envLoaderCode);\n    fs.writeFileSync(serverModuleSrcPath, serverModuleCode);\n    fs.writeFileSync(ssrClientStubPath, ssrClientStubCode);\n    fs.writeFileSync(ssrTransitionsStubPath, ssrTransitionsStubCode);\n    fs.writeFileSync(ssrPrefetchStubPath, ssrPrefetchStubCode);\n\n    // Bundle with esbuild\n    try {\n        await esbuild({\n            entryPoints: [entryPath],\n            outfile: path.join(root, \"dist\", \"server.js\"),\n            bundle: true,\n            platform: \"node\",\n            format: \"esm\",\n            jsx: \"automatic\",\n            jsxImportSource: \"react\",\n            plugins: [\n                {\n                    name: \"helium-ssr-client-alias\",\n                    setup(build) {\n                        build.onResolve({ filter: /^heliumts\\/client$/ }, () => ({ path: ssrClientStubPath }));\n                        build.onResolve({ filter: /^heliumts\\/client\\/transitions$/ }, () => ({ path: ssrTransitionsStubPath }));\n                        build.onResolve({ filter: /^heliumts\\/client\\/prefetch$/ }, () => ({ path: ssrPrefetchStubPath }));\n                    },\n                },\n            ],\n            external: [\n                // External common database and heavy dependencies\n                \"mongodb\",\n                \"mongoose\",\n                \"pg\",\n                \"mysql\",\n                \"mysql2\",\n                \"sqlite3\",\n                \"better-sqlite3\",\n                \"redis\",\n                // Node.js built-ins are automatically external, but let's be explicit\n                \"crypto\",\n                \"fs\",\n                \"path\",\n                \"http\",\n                \"https\",\n                \"stream\",\n                \"zlib\",\n                \"util\",\n            ],\n            target: \"node18\",\n            metafile: true,\n            banner: {\n                js: \"import { createRequire } from 'module'; const require = createRequire(import.meta.url);\",\n            },\n        });\n\n        // Display server build output\n        const serverOutputPath = path.relative(root, path.join(root, \"dist\", \"server.js\"));\n        const serverStats = fs.statSync(path.join(root, \"dist\", \"server.js\"));\n        const serverSizeKB = (serverStats.size / 1024).toFixed(2);\n        log(\"info\", `  ${serverOutputPath.padEnd(35)} ${serverSizeKB.padStart(8)} kB`);\n\n        log(\"info\", \"Server build complete.\");\n\n        // Transpile helium.config.ts to helium.config.js if it exists\n        const configTsPath = path.join(root, \"helium.config.ts\");\n        if (fs.existsSync(configTsPath)) {\n            log(\"info\", \"Transpiling helium.config.ts...\");\n            try {\n                await esbuild({\n                    entryPoints: [configTsPath],\n                    outfile: path.join(root, \"dist\", \"helium.config.js\"),\n                    bundle: false,\n                    platform: \"node\",\n                    format: \"esm\",\n                    target: \"node18\",\n                });\n                log(\"info\", \"Config file transpiled to dist/helium.config.js\");\n            } catch (e) {\n                log(\"warn\", \"Failed to transpile config file:\", e);\n                log(\"warn\", \"You may need to manually rename helium.config.ts to helium.config.js\");\n            }\n        } else {\n            // Check if .js or .mjs config exists and copy it to dist\n            const configJsPath = path.join(root, \"helium.config.js\");\n            const configMjsPath = path.join(root, \"helium.config.mjs\");\n\n            if (fs.existsSync(configJsPath)) {\n                fs.copyFileSync(configJsPath, path.join(root, \"dist\", \"helium.config.js\"));\n                log(\"info\", \"Copied helium.config.js to dist/\");\n            } else if (fs.existsSync(configMjsPath)) {\n                fs.copyFileSync(configMjsPath, path.join(root, \"dist\", \"helium.config.mjs\"));\n                log(\"info\", \"Copied helium.config.mjs to dist/\");\n            }\n        }\n\n        log(\"info\", \"--------------------------------\");\n        log(\"info\", \"✓ Build finished successfully.\");\n        log(\"info\", \"▶ Run 'helium start' to start the production server.\");\n\n        // Exit cleanly after build completes\n        process.exit(0);\n    } catch (e) {\n        log(\"error\", \"Server build failed:\", e);\n        process.exit(1);\n    }\n});\n\ncli.command(\"start\", \"Start production server\").action(async () => {\n    const serverPath = path.join(root, \"dist\", \"server.js\");\n    if (!fs.existsSync(serverPath)) {\n        log(\"error\", 'Server build not found. Run \"helium build\" first.');\n        process.exit(1);\n    }\n\n    // When running in production, look for config in dist directory first\n    // This allows the transpiled config to be found\n    const server = spawn(\"node\", [serverPath], {\n        stdio: \"inherit\",\n        shell: true,\n        env: { ...process.env, HELIUM_CONFIG_DIR: path.join(root, \"dist\") },\n    });\n    server.on(\"close\", (code) => {\n        process.exit(code || 0);\n    });\n});\n\ncli.help();\ncli.parse();\n"]}

package/dist/client/Router.d.ts

@@ -76,6 +76,7 @@ export declare function Link(props: LinkProps): import("react/jsx-runtime").JSX.
 export type AppShellProps<TPageProps extends Record<string, unknown> = Record<string, unknown>> = {
     Component: ComponentType<TPageProps>;
     pageProps: TPageProps;
+    children?: React.ReactNode;
 };
 export declare function AppRouter({ AppShell }: {
     AppShell?: ComponentType<AppShellProps>;

package/dist/client/Router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../src/client/Router.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAuD,MAAM,OAAO,CAAC;AAS5E,KAAK,WAAW,GAAG,YAAY,GAAG,mBAAmB,CAAC;AACtD,KAAK,aAAa,GAAG,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,KAAK,IAAI,CAAC;AAgKhG,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACpC,qDAAqD;IACrD,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB;AAGD,KAAK,aAAa,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,YAAY,EAAE,eAAe,CAAC;IAC9B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAChE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACnE,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,KAAK,MAAM,IAAI,CAAC;IAChE,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,8GAA8G;IAC9G,SAAS,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,eAAO,MAAM,aAAa,qCAAkD,CAAC;AAE7E;;;;;;;;GAQG;AACH,wBAAgB,SAAS,kBAmCxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,EAAE,OAAe,EAAE,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,QAyBlF;AA6CD,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,iBAAiB,CAC3C,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,GAAG;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qDAAqD;IACrD,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB,CACJ,CAAC;AA+BF;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,2CA4DpC;AAGD;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC9F,SAAS,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACrC,SAAS,EAAE,UAAU,CAAC;CACzB,CAAC;AAGF,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CAAE,2CAuHlF"}
+{"version":3,"file":"Router.d.ts","sourceRoot":"","sources":["../../src/client/Router.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAuD,MAAM,OAAO,CAAC;AA2D5E,KAAK,WAAW,GAAG,YAAY,GAAG,mBAAmB,CAAC;AACtD,KAAK,aAAa,GAAG,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,KAAK,IAAI,CAAC;AAgKhG,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACpC,qDAAqD;IACrD,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB;AAGD,KAAK,aAAa,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,YAAY,EAAE,eAAe,CAAC;IAC9B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAChE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,KAAK,IAAI,CAAC;IACnE,EAAE,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,KAAK,MAAM,IAAI,CAAC;IAChE,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,8GAA8G;IAC9G,SAAS,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,eAAO,MAAM,aAAa,qCAAkD,CAAC;AAE7E;;;;;;;;GAQG;AACH,wBAAgB,SAAS,kBAmCxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,EAAE,OAAe,EAAE,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,QAyBlF;AA6CD,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,iBAAiB,CAC3C,IAAI,CAAC,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,GAAG;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qDAAqD;IACrD,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB,CACJ,CAAC;AA+BF;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,2CA4DpC;AAGD;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC9F,SAAS,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACrC,SAAS,EAAE,UAAU,CAAC;IACtB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC9B,CAAC;AAGF,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CAAE,2CA0KlF"}

package/dist/client/Router.js

@@ -4,6 +4,38 @@ import { SEO_METADATA_RPC_METHOD } from "../runtime/internalMethods.js";
 import { isDevEnvironment } from "./env.js";
 import { buildRoutes } from "./routerManifest.js";
 import { isAutoHttpOnMobileEnabled, isMobileRpcDevice, rpcCallWithOptions } from "./rpcClient.js";
+function getInitialSSRBootstrap() {
+    if (typeof window === "undefined") {
+        return null;
+    }
+    const globalWindow = window;
+    const payload = globalWindow.__HELIUM_SSR_DATA__;
+    if (!payload || typeof payload !== "object" || typeof payload.path !== "string" || typeof payload.props !== "object" || payload.props === null) {
+        return null;
+    }
+    return payload;
+}
+async function fetchSSRPageProps(path) {
+    try {
+        const response = await fetch(`/__helium__/page-props?path=${encodeURIComponent(path)}`, {
+            method: "GET",
+            headers: {
+                Accept: "application/json",
+            },
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const payload = (await response.json());
+        if (!payload.ssr || !payload.props) {
+            return null;
+        }
+        return payload.props;
+    }
+    catch {
+        return null;
+    }
+}
 class RouterEventEmitter {
     constructor() {
         this.listeners = new Map();
@@ -349,6 +381,17 @@ export function AppRouter({ AppShell }) {
     // Use useSyncExternalStore to subscribe to location changes
     // This ensures synchronous updates when location changes
     const state = useSyncExternalStore(subscribeToLocation, getLocationSnapshot, getServerSnapshot);
+    const [runtimeSSRProps, setRuntimeSSRProps] = React.useState(() => {
+        const payload = getInitialSSRBootstrap();
+        if (!payload) {
+            return {};
+        }
+        if (payload.path === window.location.pathname) {
+            return payload.props;
+        }
+        return {};
+    });
+    const [hydrationDone, setHydrationDone] = React.useState(false);
     const match = useMemo(() => matchRoute(state.path, routes), [state.path, routes]);
     // Use matched params, or fall back to re-extracting from path using global routes during HMR
     const currentParams = match?.params ?? (isDevEnvironment() ? extractParamsFromPath(state.path) : {});
@@ -374,6 +417,30 @@ export function AppRouter({ AppShell }) {
         isNavigating: state.isNavigating,
         isPending,
     };
+    React.useEffect(() => {
+        const targetPath = `${state.path}${window.location.search || ""}`;
+        // On first client render, if SSR payload already exists for this path, keep it.
+        if (!hydrationDone) {
+            const bootstrap = getInitialSSRBootstrap();
+            if (bootstrap && bootstrap.path === state.path) {
+                setHydrationDone(true);
+                return;
+            }
+            setHydrationDone(true);
+        }
+        let cancelled = false;
+        const load = async () => {
+            const props = await fetchSSRPageProps(targetPath);
+            if (cancelled) {
+                return;
+            }
+            setRuntimeSSRProps(props ?? {});
+        };
+        void load();
+        return () => {
+            cancelled = true;
+        };
+    }, [state.path, currentSearchParams.toString(), hydrationDone]);
     React.useEffect(() => {
         const controller = new AbortController();
         const targetPath = `${state.path}${window.location.search || ""}`;
@@ -406,6 +473,7 @@ export function AppRouter({ AppShell }) {
     }
     const Page = match.route.Component;
     const pageProps = {
+        ...runtimeSSRProps,
         params: match.params,
         searchParams: currentSearchParams,
     };
@@ -419,7 +487,7 @@ export function AppRouter({ AppShell }) {
         }
         return content;
     };
-    const finalContent = AppShell ? _jsx(AppShell, { Component: WrappedPage, pageProps: {} }) : _jsx(WrappedPage, {});
+    const finalContent = AppShell ? (_jsx(AppShell, { Component: WrappedPage, pageProps: pageProps, children: _jsx(WrappedPage, {}) })) : (_jsx(WrappedPage, {}));
     return _jsx(RouterContext.Provider, { value: routerValue, children: finalContent });
 }
 function applyRouteMetadata(meta) {