hadars 0.2.1 → 0.2.2-rc.1

package/README.md

@@ -19,30 +19,30 @@ Bring your own router (or none), keep your components as plain React, and get SS
 ## Benchmarks
 
 <!-- BENCHMARK_START -->
-> Last run: 2026-03-20 · 60s · 100 connections · Bun runtime
-> hadars is **8.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 | **159** | 18 |
-| Latency median | **598 ms** | 2644 ms |
-| Latency p99 | **953 ms** | 6436 ms |
-| Throughput | **45.24** MB/s | 10.28 MB/s |
-| Peak RSS | 1027.8 MB | **469.8 MB** |
-| Avg RSS | 794.1 MB | **417.9 MB** |
-| Build time | 0.8 s | 5.8 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 | **17 ms** | 45 ms |
-| FCP | **88 ms** | 128 ms |
-| DOMContentLoaded | **36 ms** | 114 ms |
-| Load | **115 ms** | 157 ms |
-| Peak RSS | 502.8 MB | **282.8 MB** |
+| 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
@@ -114,6 +114,9 @@ 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]
 
@@ -181,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
 
@@ -216,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).

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,91 @@ 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(
@@ -460,7 +548,7 @@ Done! Next steps:
 // ── CLI entry ─────────────────────────────────────────────────────────────────
 
 function usage(): void {
-  console.log('Usage: hadars <new <name> | dev | build | run | export lambda [output.mjs] | export cloudflare [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> {
@@ -516,8 +604,12 @@ export async function runCli(argv: string[], cwd = process.cwd()): Promise<void>
                 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`)
+                console.error(`Unknown export target: ${subCmd ?? '(none)'}. Supported: lambda, cloudflare, static`)
                 process.exit(1)
             }
         }

package/dist/{chunk-HWOLYLPF.js → chunk-H72BZXOA.js}

@@ -171,7 +171,7 @@ var getReactResponse = async (req, opts) => {
     head: { title: "Hadars App", meta: {}, link: {}, style: {}, script: {}, status: 200 }
   };
   let props = {
-    ...getInitProps ? await getInitProps(req) : {},
+    ...getInitProps ? await getInitProps(req, opts.staticCtx) : {},
     location: req.location,
     context
   };
@@ -197,7 +197,7 @@ var getReactResponse = async (req, opts) => {
     }
   };
   const finalize = async () => {
-    const { context: _, ...restProps } = getFinalProps ? await getFinalProps(props) : props;
+    const restProps = getFinalProps ? await getFinalProps(props) : props;
     const serverData = {};
     let hasServerData = false;
     for (const [key, entry] of unsuspend.cache) {