hadars 0.1.35 → 0.1.37

package/README.md

@@ -88,6 +88,9 @@ hadars build
 
 # Serve the production build
 hadars run
+
+# Bundle the app into a single self-contained Lambda .mjs file
+hadars export lambda [output.mjs]
 ```
 
 ## Features
@@ -142,6 +145,8 @@ const UserCard = ({ userId }: { userId: string }) => {
 | `proxyCORS` | `boolean` | - | Inject CORS headers on proxied responses |
 | `define` | `Record` | - | Compile-time constants for rspack's DefinePlugin |
 | `swcPlugins` | `array` | - | Extra SWC plugins (e.g. Relay compiler) |
+
+> **Environment variables in client bundles:** `process.env.*` references in client-side code are replaced at build time by rspack's DefinePlugin. They are **not** read at runtime in the browser. Use the `define` option to expose specific values, or keep env var access inside `getInitProps` / `fetch` (server-only code) so they are resolved at request time.
 | `moduleRules` | `array` | - | Extra rspack module rules appended to the built-in set (client + SSR) |
 | `fetch` | `function` | - | Custom fetch handler; return a `Response` to short-circuit SSR |
 | `websocket` | `object` | - | WebSocket handler (Bun only) |
@@ -184,6 +189,78 @@ const config: HadarsOptions = {
 export default config;
 ```
 
+## AWS Lambda
+
+hadars apps can be deployed to AWS Lambda backed by API Gateway (HTTP API v2 or REST API v1).
+
+### File-based deployment
+
+Run `hadars build`, then create a Lambda entry file that imports `createLambdaHandler` from `hadars/lambda`:
+
+```ts
+// lambda-entry.ts
+import { createLambdaHandler } from 'hadars/lambda';
+import config from './hadars.config';
+
+export const handler = createLambdaHandler(config);
+```
+
+Deploy the entire project directory (including the `.hadars/` output folder) as your Lambda package. Static assets (JS, CSS, fonts) under `.hadars/static/` are served directly by the Lambda handler — for production, front the function with CloudFront and route static paths to an S3 origin instead.
+
+### Single-file bundle
+
+`hadars export lambda` produces a completely self-contained `.mjs` file that requires no `.hadars/` directory on disk. The SSR module and HTML template are inlined at build time. Static assets must be served separately (S3 + CloudFront).
+
+```bash
+# Outputs lambda.mjs in the current directory
+hadars export lambda
+
+# Custom output path
+hadars export lambda dist/lambda.mjs
+```
+
+The command:
+1. Runs `hadars build`
+2. Generates a temporary entry shim with static imports of the SSR module and `out.html`
+3. Bundles everything into a single ESM `.mjs` with esbuild (`.html` files loaded as text, Node built-ins kept external)
+4. Prints deploy instructions
+
+**Deploy steps:**
+1. Upload the output `.mjs` as your Lambda function code
+2. Set the handler to `index.handler`
+3. Upload `.hadars/static/` assets to S3 and serve via CloudFront
+
+### `createLambdaHandler` API
+
+```ts
+import { createLambdaHandler, type LambdaBundled } from 'hadars/lambda';
+
+// File-based (reads .hadars/ at runtime)
+export const handler = createLambdaHandler(config);
+
+// Bundled (zero I/O — for use with `hadars export lambda` output)
+import * as ssrModule from './.hadars/index.ssr.js';
+import outHtml from './.hadars/static/out.html';
+export const handler = createLambdaHandler(config, { ssrModule, outHtml });
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `options` | `HadarsOptions` | Same config object used for `dev`/`run` |
+| `bundled` | `LambdaBundled` *(optional)* | Pre-loaded SSR module + HTML; eliminates all runtime file I/O |
+
+The handler accepts both **API Gateway HTTP API (v2)** and **REST API (v1)** event formats. Binary responses (images, fonts, pre-compressed assets) are automatically base64-encoded.
+
+### Environment variables on Lambda
+
+`process.env` is available in all server-side code (`getInitProps`, `fetch`, `cache`, etc.) and is resolved at runtime per invocation — Lambda injects env vars into the process before your handler runs.
+
+Client-side code (anything that runs in the browser) is an exception: `process.env.*` references are substituted **at build time** by rspack. They will not reflect Lambda env vars set after the build. Expose runtime values to the client by returning them from `getInitProps` instead, or use the `define` option for values that are known at build time.
+
+### `useServerData` on Lambda
+
+Client-side navigation sends a `GET <url>` request with `Accept: application/json` to refetch server data. The Lambda handler returns a JSON `{ serverData }` map for these requests — the same as the regular server does — so `useServerData` works identically in both deployment modes.
+
 ## slim-react
 
 hadars ships its own lightweight React-compatible SSR renderer called **slim-react** (`src/slim-react/`). It replaces `react-dom/server` on the server side entirely.

package/cli-lib.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
-import { mkdir, writeFile } from 'node:fs/promises'
-import { resolve, join } from 'node:path'
+import { mkdir, writeFile, unlink } from 'node:fs/promises'
+import { resolve, join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import * as Hadars from './src/build'
 import type { HadarsOptions } from './src/types/hadars'
 
@@ -42,7 +43,81 @@ async function loadConfig(configPath: string): Promise<HadarsOptions> {
   return (mod && (mod.default ?? mod)) as HadarsOptions
 }
 
-// ── hadars new ────────────────────────────────────────────────────────────────
+// ── hadars export lambda ────────────────────────────────────────────────────
+
+async function bundleLambda(
+    config: HadarsOptions,
+    configPath: string,
+    outputFile: string,
+    cwd: string,
+): Promise<void> {
+    // 1. Ensure the hadars production build is up to date.
+    console.log('Building hadars project...')
+    await Hadars.build({ ...config, mode: 'production' })
+
+    // 2. Resolve paths.
+    const ssrBundle = resolve(cwd, '.hadars', 'index.ssr.js')
+    const outHtml   = resolve(cwd, '.hadars', 'static', 'out.html')
+
+    if (!existsSync(ssrBundle)) {
+        console.error(`SSR bundle not found: ${ssrBundle}`)
+        process.exit(1)
+    }
+    if (!existsSync(outHtml)) {
+        console.error(`HTML template not found: ${outHtml}`)
+        process.exit(1)
+    }
+
+    // 3. Write a temporary entry shim that statically imports the SSR module
+    //    and the HTML template so esbuild can inline both.
+    // Write the shim inside cwd so esbuild's module resolution finds local
+    // node_modules when walking up from the shim's directory.
+    // Use the absolute path to lambda.js (sibling of the CLI in dist/) so the
+    // shim doesn't depend on package name resolution at all.
+    const lambdaModule = resolve(dirname(fileURLToPath(import.meta.url)), 'lambda.js')
+    const shimPath = join(cwd, `.hadars-lambda-shim-${Date.now()}.ts`)
+    const shim = [
+        `import * as ssrModule from ${JSON.stringify(ssrBundle)};`,
+        `import outHtml from ${JSON.stringify(outHtml)};`,
+        `import { createLambdaHandler } from ${JSON.stringify(lambdaModule)};`,
+        `import config from ${JSON.stringify(configPath)};`,
+        `export const handler = createLambdaHandler(config as any, { ssrModule: ssrModule as any, outHtml });`,
+    ].join('\n') + '\n'
+    await writeFile(shimPath, shim, 'utf-8')
+
+    // 4. Bundle with esbuild.
+    try {
+        const { build: esbuild } = await import('esbuild')
+        console.log(`Bundling Lambda handler → ${outputFile}`)
+        await esbuild({
+            entryPoints: [shimPath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: ['node20'],
+            outfile: outputFile,
+            sourcemap: false,
+            loader: { '.html': 'text', '.tsx': 'tsx', '.ts': 'ts' },
+            // @rspack/* contains native binaries and is build-time only —
+            // it is never imported at Lambda runtime, so mark it external.
+            // Everything else (React, hadars runtime, etc.) is bundled in to
+            // produce a truly self-contained single-file deployment.
+            external: ['@rspack/*'],
+        })
+        console.log(`Lambda bundle written to ${outputFile}`)
+        console.log(`\nDeploy instructions:`)
+        console.log(`  1. Create a staging directory with just this file:`)
+        console.log(`       mkdir -p lambda-deploy && cp ${outputFile} lambda-deploy/lambda.mjs`)
+        console.log(`  2. Upload lambda-deploy/ as your Lambda function code`)
+        console.log(`  3. Set handler to: lambda.handler  (runtime: Node.js 20.x)`)
+        console.log(`  4. Upload .hadars/static/ assets to S3 and serve via CloudFront`)
+        console.log(`     (the Lambda handler does not serve static JS/CSS — route those to S3)`)
+    } finally {
+        await unlink(shimPath).catch(() => {})
+    }
+}
+
+
 
 const TEMPLATES: Record<string, (name: string) => string> = {
   'package.json': (name: string) => JSON.stringify({
@@ -313,7 +388,7 @@ Done! Next steps:
 // ── CLI entry ─────────────────────────────────────────────────────────────────
 
 function usage(): void {
-  console.log('Usage: hadars <new <name> | dev | build | run>')
+  console.log('Usage: hadars <new <name> | dev | build | run | export lambda [output.mjs]>')
 }
 
 export async function runCli(argv: string[], cwd = process.cwd()): Promise<void> {
@@ -334,7 +409,7 @@ export async function runCli(argv: string[], cwd = process.cwd()): Promise<void>
     return
   }
 
-  if (!cmd || !['dev', 'build', 'run'].includes(cmd)) {
+  if (!cmd || !['dev', 'build', 'run', 'export'].includes(cmd)) {
     usage()
     process.exit(1)
   }
@@ -359,6 +434,16 @@ export async function runCli(argv: string[], cwd = process.cwd()): Promise<void>
             await build(cfg);
             console.log('Build complete')
             process.exit(0)
+        case 'export': {
+            const subCmd = argv[3]
+            if (subCmd !== 'lambda') {
+                console.error(`Unknown export target: ${subCmd ?? '(none)'}. Did you mean: hadars export lambda`)
+                process.exit(1)
+            }
+            const outputFile = resolve(cwd, argv[4] ?? 'lambda.mjs')
+            await bundleLambda(cfg, configPath, outputFile, cwd)
+            process.exit(0)
+        }
         case 'run':
             console.log('Running project...')
             await run(cfg);