hadars 0.2.0 → 0.2.2-rc.0

package/README.md

@@ -19,27 +19,30 @@ Bring your own router (or none), keep your components as plain React, and get SS
 ## Benchmarks
 
 <!-- BENCHMARK_START -->
-> Last run: 2026-03-18 · 60s · 200 connections · Bun runtime
-> hadars is **7.8x faster** in requests/sec
+> Last run: 2026-03-21 · 60s · 100 connections · Bun runtime
+> hadars is **8.7x faster** in requests/sec
 
 **Throughput** (autocannon, 60s)
 
 | Metric | hadars | Next.js |
 |---|---:|---:|
-| Requests/sec | **132** | 17 |
-| Latency median | **1490 ms** | 2757 ms |
-| Latency p99 | **2289 ms** | 6742 ms |
-| Throughput | **37.38** MB/s | 9.37 MB/s |
-| Build time | 0.7 s | 6.3 s |
+| Requests/sec | **148** | 17 |
+| Latency median | **647 ms** | 2712 ms |
+| Latency p99 | **969 ms** | 6544 ms |
+| Throughput | **42.23** MB/s | 9.29 MB/s |
+| Peak RSS | 1062.8 MB | **472.3 MB** |
+| Avg RSS | 799.7 MB | **404.7 MB** |
+| Build time | 0.7 s | 6.0 s |
 
 **Page load** (Playwright · Chromium headless · median)
 
 | Metric | hadars | Next.js |
 |---|---:|---:|
-| TTFB | **22 ms** | 42 ms |
-| FCP | **124 ms** | 136 ms |
-| DOMContentLoaded | **88 ms** | 126 ms |
-| Load | **155 ms** | 173 ms |
+| TTFB | **20 ms** | 43 ms |
+| FCP | **100 ms** | 136 ms |
+| DOMContentLoaded | **41 ms** | 127 ms |
+| Load | **127 ms** | 174 ms |
+| Peak RSS | 444.7 MB | **284.9 MB** |
 <!-- BENCHMARK_END -->
 
 ## Quick start
@@ -76,17 +79,17 @@ export default config;
 **src/App.tsx**
 ```tsx
 import React from 'react';
-import { HadarsContext, HadarsHead, type HadarsApp, type HadarsRequest } from 'hadars';
+import { HadarsHead, type HadarsApp, type HadarsRequest } from 'hadars';
 
 interface Props { user: { name: string } }
 
-const App: HadarsApp<Props> = ({ user, context }) => (
-    <HadarsContext context={context}>
+const App: HadarsApp<Props> = ({ user }) => (
+    <>
         <HadarsHead status={200}>
             <title>Hello {user.name}</title>
         </HadarsHead>
         <h1>Hello, {user.name}!</h1>
-    </HadarsContext>
+    </>
 );
 
 export const getInitProps = async (req: HadarsRequest): Promise<Props> => ({
@@ -111,8 +114,14 @@ hadars build
 # Serve the production build
 hadars run
 
+# Pre-render every page to static HTML files (output goes to out/ by default)
+hadars export static [outDir]
+
 # Bundle the app into a single self-contained Lambda .mjs file
 hadars export lambda [output.mjs]
+
+# Bundle the app into a single self-contained Cloudflare Worker .mjs file
+hadars export cloudflare [output.mjs]
 ```
 
 ## Features
@@ -175,6 +184,9 @@ const UserCard = ({ userId }: { userId: string }) => {
 | `htmlTemplate` | `string` | - | Path to a custom HTML template with `HADARS_HEAD` / `HADARS_BODY` markers |
 | `optimization` | `object` | - | Override rspack `optimization` for production client builds |
 | `cache` | `function` | - | SSR response cache for `run()` mode; return `{ key, ttl? }` to cache a request |
+| `paths` | `function` | - | Returns URL list to pre-render with `hadars export static`; receives `HadarsStaticContext` |
+| `sources` | `array` | - | Gatsby-compatible source plugins; hadars infers a GraphQL schema from their nodes |
+| `graphql` | `function` | - | Custom GraphQL executor passed to `paths()` and `getInitProps()` as `ctx.graphql` |
 
 ### moduleRules example
 
@@ -210,6 +222,163 @@ const config: HadarsOptions = {
 export default config;
 ```
 
+## Static Export
+
+> **Experimental.** Static export and Gatsby-compatible source plugins are new features. The API — including config shape, context object, and schema inference behaviour — may change in future releases without a major version bump.
+
+Pre-render every page to a plain HTML file and deploy to any static host — no server required.
+
+```bash
+# Output goes to out/ by default
+hadars export static
+
+# Custom output directory
+hadars export static dist
+```
+
+Add a `paths` function to `hadars.config.ts` that returns the list of URLs to pre-render:
+
+```ts
+// hadars.config.ts
+import type { HadarsOptions } from 'hadars';
+
+export default {
+    entry: './src/App.tsx',
+    paths: () => ['/', '/about', '/contact'],
+} satisfies HadarsOptions;
+```
+
+Each URL is written as `<outDir>/<path>/index.html` plus an `index.json` sidecar so `useServerData` keeps working on client-side navigation without a live server. Static assets are copied from `.hadars/static/`.
+
+### Data in static pages
+
+`getInitProps` receives a `HadarsStaticContext` as its second argument during static export. Use it to fetch data from a database, API, or GraphQL layer:
+
+```ts
+import type { HadarsApp, HadarsRequest, HadarsStaticContext } from 'hadars';
+
+export const getInitProps = async (
+    req: HadarsRequest,
+    ctx?: HadarsStaticContext,
+): Promise<Props> => {
+    if (!ctx) return { posts: [] };
+    const { data } = await ctx.graphql('{ allPost { id title } }');
+    return { posts: data?.allPost ?? [] };
+};
+```
+
+## Source Plugins
+
+hadars source plugins follow the same API as Gatsby's `sourceNodes` — so most existing Gatsby CMS source plugins work out of the box. Each plugin creates typed nodes in an in-memory store; hadars infers a GraphQL schema automatically and exposes it to `paths()` and `getInitProps()`.
+
+During `hadars dev`, a GraphiQL IDE is available at `/__hadars/graphql` so you can explore the inferred schema while you build.
+
+### Install graphql
+
+Schema inference requires `graphql` to be installed in your project:
+
+```bash
+npm install graphql
+```
+
+### Config
+
+```ts
+// hadars.config.ts
+import type { HadarsOptions, HadarsStaticContext } from 'hadars';
+
+export default {
+    entry: './src/App.tsx',
+
+    sources: [
+        {
+            resolve: 'gatsby-source-contentful',
+            options: {
+                spaceId: process.env.CONTENTFUL_SPACE_ID,
+                accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
+            },
+        },
+    ],
+
+    paths: async ({ graphql }: HadarsStaticContext) => {
+        const { data } = await graphql(`{ allContentfulBlogPost { slug } }`);
+        const slugs = data?.allContentfulBlogPost?.map((p: any) => p.slug) ?? [];
+        return ['/', ...slugs.map((s: string) => `/post/${s}`)];
+    },
+} satisfies HadarsOptions;
+```
+
+### Local source plugin
+
+Pass a pre-imported module instead of a package name to use a local plugin without publishing it to npm:
+
+```ts
+// src/posts-source.ts
+export async function sourceNodes(
+    { actions, createNodeId, createContentDigest }: any,
+    options: { dataDir: string } = {},
+) {
+    const { createNode } = actions;
+    const posts = await fetchPostsFromMyApi();
+    for (const post of posts) {
+        createNode({
+            ...post,
+            id: createNodeId(post.slug),
+            internal: { type: 'BlogPost', contentDigest: createContentDigest(post) },
+        });
+    }
+}
+```
+
+```ts
+// hadars.config.ts
+import * as postsSource from './src/posts-source';
+
+export default {
+    entry: './src/App.tsx',
+    sources: [{ resolve: postsSource }],
+    paths: async ({ graphql }) => {
+        const { data } = await graphql('{ allBlogPost { slug } }');
+        return ['/', ...(data?.allBlogPost ?? []).map((p: any) => `/post/${p.slug}`)];
+    },
+} satisfies HadarsOptions;
+```
+
+### Inferred GraphQL schema
+
+For each node type (e.g. `BlogPost`) you get two root queries:
+
+| Query | Returns |
+|---|---|
+| `allBlogPost` | Every BlogPost node |
+| `blogPost(id, slug, title, …)` | First node matching all supplied args |
+
+All scalar fields are automatically added as optional lookup arguments, so you can do `blogPost(slug: "hello")` without knowing the hashed node id.
+
+### Custom GraphQL executor
+
+Skip `sources` and provide a `graphql` executor directly for full control over resolvers:
+
+```ts
+import { graphql, buildSchema } from 'graphql';
+import type { HadarsOptions } from 'hadars';
+
+const schema = buildSchema(`
+    type Post { id: ID! title: String slug: String }
+    type Query { allPost: [Post!]! }
+`);
+
+export default {
+    entry: './src/App.tsx',
+    graphql: (query, variables) =>
+        graphql({ schema, rootValue: { allPost: fetchPostsFromDb }, source: query, variableValues: variables }),
+    paths: async ({ graphql }) => {
+        const { data } = await graphql('{ allPost { slug } }');
+        return ['/', ...(data?.allPost ?? []).map((p: any) => `/post/${p.slug}`)];
+    },
+} satisfies HadarsOptions;
+```
+
 ## AWS Lambda
 
 hadars apps can be deployed to AWS Lambda backed by API Gateway (HTTP API v2 or REST API v1).
@@ -282,6 +451,69 @@ Client-side code (anything that runs in the browser) is an exception: `process.e
 
 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.
 
+## Cloudflare Workers
+
+hadars apps can be deployed to Cloudflare Workers. The Worker handles SSR; static assets (JS, CSS, fonts) are served from R2 or another CDN.
+
+### Single-file bundle
+
+`hadars export cloudflare` produces a self-contained `.mjs` Worker script. Unlike the Lambda adapter, no event format conversion is needed — Cloudflare Workers natively use the Web `Request`/`Response` API.
+
+```bash
+# Outputs cloudflare.mjs in the current directory
+hadars export cloudflare
+
+# Custom output path
+hadars export cloudflare dist/worker.mjs
+```
+
+The command:
+1. Runs `hadars build`
+2. Generates an entry shim with static imports of the SSR module and `out.html`
+3. Bundles everything into a single ESM `.mjs` with esbuild (`platform: browser`, `target: es2022`)
+4. Prints wrangler deploy instructions
+
+### Deploy steps
+
+1. Add a `wrangler.toml` pointing at the output file:
+
+```toml
+name = "my-app"
+main = "cloudflare.mjs"
+compatibility_date = "2024-09-23"
+compatibility_flags = ["nodejs_compat"]
+```
+
+2. Upload `.hadars/static/` assets to R2 and configure routing rules so static file extensions (`*.js`, `*.css`, etc.) are served from R2 and all other requests go to the Worker.
+
+3. Deploy:
+
+```bash
+wrangler deploy
+```
+
+### `createCloudflareHandler` API
+
+```ts
+import { createCloudflareHandler, type CloudflareBundled } from 'hadars/cloudflare';
+import * as ssrModule from './.hadars/index.ssr.js';
+import outHtml from './.hadars/static/out.html';
+import config from './hadars.config';
+
+export default createCloudflareHandler(config, { ssrModule, outHtml });
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `options` | `HadarsOptions` | Same config object used for `dev`/`run` |
+| `bundled` | `CloudflareBundled` | Pre-loaded SSR module + HTML template |
+
+The returned object is a standard Cloudflare Workers export (`{ fetch(req, env, ctx) }`).
+
+### CPU time
+
+hadars uses [slim-react](#slim-react) for SSR which is synchronous and typically renders a page in under 3 ms — well within Cloudflare's 10 ms free-plan CPU budget. Paid plans (Workers Paid) have no CPU time limit.
+
 ## 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,9 +1,12 @@
 import { existsSync } from 'node:fs'
-import { mkdir, writeFile, unlink } from 'node:fs/promises'
+import { mkdir, writeFile, unlink, readFile } from 'node:fs/promises'
 import { resolve, join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import * as Hadars from './src/build'
-import type { HadarsOptions } from './src/types/hadars'
+import type { HadarsOptions, HadarsEntryModule } from './src/types/hadars'
+import { renderStaticSite } from './src/static'
+import { runSources } from './src/source/runner'
+import { buildSchemaExecutor } from './src/source/inference'
 
 const SUPPORTED = ['hadars.config.js', 'hadars.config.mjs', 'hadars.config.cjs', 'hadars.config.ts']
 
@@ -43,6 +46,163 @@ async function loadConfig(configPath: string): Promise<HadarsOptions> {
   return (mod && (mod.default ?? mod)) as HadarsOptions
 }
 
+// ── hadars export static ─────────────────────────────────────────────────────
+
+async function exportStatic(
+    config: HadarsOptions,
+    outputDir: string,
+    cwd: string,
+): Promise<void> {
+    if (!config.paths) {
+        console.error(
+            'Error: `paths` is not defined in your hadars config.\n' +
+            'Add a `paths` function that returns the list of URLs to pre-render:\n\n' +
+            '  paths: () => [\'/\', \'/about\', \'/contact\']\n',
+        )
+        process.exit(1)
+    }
+
+    console.log('Building hadars project...')
+    await Hadars.build({ ...config, mode: 'production' })
+
+    const ssrBundle = resolve(cwd, '.hadars', 'index.ssr.js')
+    const outHtml   = resolve(cwd, '.hadars', 'static', 'out.html')
+    const staticSrc = resolve(cwd, '.hadars', 'static')
+
+    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)
+    }
+
+    const ssrModule  = await import(pathToFileURL(ssrBundle).href) as HadarsEntryModule<any>
+    const htmlSource = await readFile(outHtml, 'utf-8')
+    const outDir     = resolve(cwd, outputDir)
+
+    // Run source plugins (if any) and build an auto-generated GraphQL executor.
+    // An explicit config.graphql always takes precedence over the inferred one.
+    let graphql = config.graphql
+    if (config.sources && config.sources.length > 0) {
+        console.log(`Running ${config.sources.length} source plugin(s)...`)
+        const store = await runSources(config.sources)
+        if (!graphql) {
+            const inferred = await buildSchemaExecutor(store)
+            if (!inferred) {
+                console.error(
+                    'Error: `graphql` package not found.\n' +
+                    'Source plugins require graphql-js to be installed:\n\n' +
+                    '  npm install graphql\n',
+                )
+                process.exit(1)
+            }
+            graphql = inferred
+            console.log(`Schema inferred for types: ${store.getTypes().join(', ') || '(none)'}`)
+        }
+    }
+
+    const staticCtx = {
+        graphql: graphql ?? (() => Promise.reject(
+            new Error('[hadars] No graphql executor configured. Add a `graphql` function to your hadars.config.'),
+        )),
+    }
+
+    const paths = await config.paths(staticCtx)
+
+    console.log(`Pre-rendering ${paths.length} page(s)...`)
+
+    const { rendered, errors } = await renderStaticSite({
+        ssrModule,
+        htmlSource,
+        staticSrc,
+        paths,
+        outputDir: outDir,
+        graphql,
+    })
+
+    for (const p of rendered) console.log(`  [200] ${p}`)
+    for (const { path, error } of errors) console.error(`  [ERR] ${path}: ${error.message}`)
+
+    console.log(`\nExported to ${outputDir}/`)
+    if (errors.length > 0) console.log(`  ${errors.length} page(s) failed`)
+    console.log(`\nServe locally:`)
+    console.log(`  npx serve ${outputDir}`)
+}
+
+// ── hadars export cloudflare ─────────────────────────────────────────────────
+
+async function bundleCloudflare(
+    config: HadarsOptions,
+    configPath: string,
+    outputFile: string,
+    cwd: string,
+): Promise<void> {
+    console.log('Building hadars project...')
+    await Hadars.build({ ...config, mode: 'production' })
+
+    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)
+    }
+
+    // Resolve cloudflare.js from the dist/ directory (sibling of cli.js).
+    const cloudflareModule = resolve(dirname(fileURLToPath(import.meta.url)), 'cloudflare.js')
+    const shimPath = join(cwd, `.hadars-cloudflare-shim-${Date.now()}.ts`)
+    const shim = [
+        `import * as ssrModule from ${JSON.stringify(ssrBundle)};`,
+        `import outHtml from ${JSON.stringify(outHtml)};`,
+        `import { createCloudflareHandler } from ${JSON.stringify(cloudflareModule)};`,
+        `import config from ${JSON.stringify(configPath)};`,
+        `export default createCloudflareHandler(config as any, { ssrModule: ssrModule as any, outHtml });`,
+    ].join('\n') + '\n'
+    await writeFile(shimPath, shim, 'utf-8')
+
+    try {
+        const { build: esbuild } = await import('esbuild')
+        console.log(`Bundling Cloudflare Worker → ${outputFile}`)
+        await esbuild({
+            entryPoints: [shimPath],
+            bundle: true,
+            // 'browser' avoids Node.js built-in shims; CF Workers uses Web APIs.
+            // If you use node:* APIs in your app code, add nodejs_compat to wrangler.toml.
+            platform: 'browser',
+            format: 'esm',
+            target: ['es2022'],
+            outfile: outputFile,
+            sourcemap: false,
+            loader: { '.html': 'text', '.tsx': 'tsx', '.ts': 'ts' },
+            // @rspack/* is build-time only — never imported at Worker runtime.
+            external: ['@rspack/*'],
+            // Cloudflare Workers supports the Web Crypto API natively; suppress
+            // esbuild's attempt to polyfill node:crypto.
+            define: { 'global': 'globalThis' },
+        })
+        console.log(`Cloudflare Worker bundle written to ${outputFile}`)
+        console.log(`\nDeploy instructions:`)
+        console.log(`  1. Ensure wrangler.toml points to the output file:`)
+        console.log(`       name = "my-app"`)
+        console.log(`       main = "${outputFile}"`)
+        console.log(`       compatibility_date = "2024-09-23"`)
+        console.log(`       compatibility_flags = ["nodejs_compat"]`)
+        console.log(`  2. Upload .hadars/static/ assets to R2 (or another CDN):`)
+        console.log(`       wrangler r2 object put my-bucket/assets/ --file .hadars/static/ --recursive`)
+        console.log(`  3. Add a route rule in wrangler.toml to send *.js / *.css to R2`)
+        console.log(`     and all other requests to the Worker.`)
+        console.log(`  4. Deploy: wrangler deploy`)
+    } finally {
+        await unlink(shimPath).catch(() => {})
+    }
+}
+
 // ── hadars export lambda ────────────────────────────────────────────────────
 
 async function bundleLambda(
@@ -172,7 +332,7 @@ dist/
 
   'src/App.tsx': () =>
 `import React from 'react';
-import { HadarsContext, HadarsHead, type HadarsApp } from 'hadars';
+import { HadarsHead, type HadarsApp } from 'hadars';
 
 const css = \`
   *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@@ -284,15 +444,15 @@ const css = \`
 
 \`;
 
-const App: HadarsApp<{}> = ({ context }) => {
+const App: HadarsApp<{}> = () => {
   const [count, setCount] = React.useState(0);
 
   return (
-    <HadarsContext context={context}>
+    <>
       <HadarsHead status={200}>
         <title>My App</title>
-        <meta id="viewport" name="viewport" content="width=device-width, initial-scale=1" />
-        <style id="app-styles" dangerouslySetInnerHTML={{ __html: css }} />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <style data-id="app-styles" dangerouslySetInnerHTML={{ __html: css }} />
       </HadarsHead>
 
       <nav className="nav">
@@ -350,7 +510,7 @@ const App: HadarsApp<{}> = ({ context }) => {
         </div>
       </div>
 
-    </HadarsContext>
+    </>
   );
 };
 
@@ -388,7 +548,7 @@ Done! Next steps:
 // ── CLI entry ─────────────────────────────────────────────────────────────────
 
 function usage(): void {
-  console.log('Usage: hadars <new <name> | dev | build | run | export lambda [output.mjs]>')
+  console.log('Usage: hadars <new <name> | dev | build | run | export lambda [output.mjs] | export cloudflare [output.mjs] | export static [outDir]>')
 }
 
 export async function runCli(argv: string[], cwd = process.cwd()): Promise<void> {
@@ -436,13 +596,22 @@ export async function runCli(argv: string[], cwd = process.cwd()): Promise<void>
             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`)
+            if (subCmd === 'lambda') {
+                const outputFile = resolve(cwd, argv[4] ?? 'lambda.mjs')
+                await bundleLambda(cfg, configPath, outputFile, cwd)
+                process.exit(0)
+            } else if (subCmd === 'cloudflare') {
+                const outputFile = resolve(cwd, argv[4] ?? 'cloudflare.mjs')
+                await bundleCloudflare(cfg, configPath, outputFile, cwd)
+                process.exit(0)
+            } else if (subCmd === 'static') {
+                const outDirArg = argv[4] ?? 'out'
+                await exportStatic(cfg, outDirArg, cwd)
+                process.exit(0)
+            } else {
+                console.error(`Unknown export target: ${subCmd ?? '(none)'}. Supported: lambda, cloudflare, static`)
                 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...')