hadars 0.1.20 → 0.1.22

package/README.md

@@ -2,23 +2,46 @@
 
 A minimal server-side rendering framework for React built on [rspack](https://rspack.dev). Runs on Bun, Node.js, and Deno.
 
-## Install
+## Why hadars?
+
+hadars is an alternative to Next.js for apps that just need SSR.
+
+**Getting out is painful.** Next.js has its own router, image component, font loader, `<Link>`, and middleware API. These aren't just conveniences - they're load-bearing parts of your app. By the time you want to leave, you're not swapping a dependency, you're doing a rewrite.
+
+**Server Components solved a problem I don't have.** The mental model is interesting, but the split between server-only and client-only trees, plus the serialisation boundary between them, adds real complexity for most apps. `getInitProps` + `useServerData` gets you server-rendered HTML with client hydration without any of that.
+
+**A smaller attack surface is better.** Any framework that intercepts every request adds risk. Less code handling that path is a reasonable starting point - whether that translates to meaningful security differences is something only time and scrutiny will tell.
+
+**Less overhead.** hadars skips RSC infrastructure, a built-in router, and edge runtime polyfills. It uses its own SSR renderer ([slim-react](#slim-react)) instead of react-dom/server. Whether that matters for your use case depends on your load, but the baseline is lighter.
+
+Bring your own router (or none), keep your components as plain React, and get SSR, HMR, and a production build from a single config file.
+
+## Quick start
+
+Scaffold a new project in seconds:
+
+```bash
+npx hadars new my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Or install manually:
 
 ```bash
 npm install hadars
 ```
 
-## Quick start
+## Example
 
 **hadars.config.ts**
 ```ts
-import os from 'os';
 import type { HadarsOptions } from 'hadars';
 
 const config: HadarsOptions = {
     entry: 'src/App.tsx',
     port: 3000,
-    workers: os.cpus().length, // multi-core production server (Node.js)
 };
 
 export default config;
@@ -49,9 +72,10 @@ export default App;
 
 ## CLI
 
-After installing hadars the `hadars` binary is available. It works on Node.js, Bun, and Deno — the runtime is auto-detected:
-
 ```bash
+# Scaffold a new project
+hadars new <project-name>
+
 # Development server with React Fast Refresh HMR
 hadars dev
 
@@ -59,19 +83,19 @@ hadars dev
 hadars build
 
 # Serve the production build
-hadars run         # multi-core when workers > 1
+hadars run
 ```
 
 ## Features
 
-- **React Fast Refresh** — full HMR via rspack-dev-server, module-level patches
-- **True SSR** — components render on the server with your data, then hydrate on the client
-- **Shell streaming** — HTML shell is flushed immediately so browsers can start loading assets before the body arrives
-- **Code splitting** — `loadModule('./Comp')` splits on the browser, bundles statically on the server
-- **Head management** — `HadarsHead` controls `<title>`, `<meta>`, `<link>` on server and client
-- **Cross-runtime** — Bun, Node.js, Deno; uses the standard Fetch API throughout
-- **Multi-core** — `workers: os.cpus().length` forks a process per CPU core via `node:cluster`
-- **TypeScript-first** — full types for props, lifecycle hooks, config, and the request object
+- **React Fast Refresh** - full HMR via rspack-dev-server, module-level patches
+- **True SSR** - components render on the server with your data, then hydrate on the client
+- **Shell streaming** - HTML shell is flushed immediately so browsers can start loading assets before the body arrives
+- **Code splitting** - `loadModule('./Comp')` splits on the browser, bundles statically on the server
+- **Head management** - `HadarsHead` controls `<title>`, `<meta>`, `<link>` on server and client
+- **Cross-runtime** - Bun, Node.js, Deno; uses the standard Fetch API throughout
+- **Multi-core** - `workers: os.cpus().length` forks a process per CPU core via `node:cluster`
+- **TypeScript-first** - full types for props, lifecycle hooks, config, and the request object
 
 ## useServerData
 
@@ -87,10 +111,10 @@ const UserCard = ({ userId }: { userId: string }) => {
 };
 ```
 
-- **`key`** — string or string array; must be stable and unique within the page
-- **Server** — calls `fn()`, awaits the result across render iterations, returns `undefined` until resolved
-- **Client** — reads the pre-resolved value from the hydration cache serialised by the server; `fn()` is never called in the browser
-- **Suspense libraries** — also works when `fn()` throws a thenable (e.g. Relay `useLazyLoadQuery` with `suspense: true`); the thrown promise is awaited and the next render re-calls `fn()` synchronously
+- **`key`** - string or string array; must be stable and unique within the page
+- **Server** - calls `fn()`, awaits the result across render iterations, returns `undefined` until resolved
+- **Client** - reads the pre-resolved value from the hydration cache serialised by the server; `fn()` is never called in the browser
+- **Suspense libraries** - also works when `fn()` throws a thenable (e.g. Relay `useLazyLoadQuery` with `suspense: true`); the thrown promise is awaited and the next render re-calls `fn()` synchronously
 
 ## Data lifecycle hooks
 
@@ -105,19 +129,74 @@ const UserCard = ({ userId }: { userId: string }) => {
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `entry` | `string` | — | Path to your page component **(required)** |
+| `entry` | `string` | - | Path to your page component **(required)** |
 | `port` | `number` | `9090` | HTTP port |
 | `hmrPort` | `number` | `port + 1` | rspack HMR dev server port |
 | `baseURL` | `string` | `""` | Public base path, e.g. `"/app"` |
-| `workers` | `number` | `1` | Worker processes in `run()` mode (Node.js only) |
-| `proxy` | `Record / fn` | — | Path-prefix proxy rules or a custom async function |
-| `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) |
-| `fetch` | `function` | — | Custom fetch handler; return a `Response` to short-circuit SSR |
-| `websocket` | `object` | — | WebSocket handler (Bun only) |
+| `workers` | `number` | `1` | Worker processes / threads in `run()` mode |
+| `proxy` | `Record / fn` | - | Path-prefix proxy rules or a custom async function |
+| `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) |
+| `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) |
 | `wsPath` | `string` | `"/ws"` | Path that triggers WebSocket upgrade |
-| `optimization` | `object` | — | Override rspack `optimization` for production client builds (merged on top of defaults) |
+| `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 |
+
+### moduleRules example
+
+Add support for any loader not included by default:
+
+```ts
+import type { HadarsOptions } from 'hadars';
+
+const config: HadarsOptions = {
+    entry: 'src/App.tsx',
+    moduleRules: [
+        {
+            test: /\.mdx?$/,
+            use: [{ loader: '@mdx-js/loader' }],
+        },
+    ],
+};
+
+export default config;
+```
+
+### SSR cache example
+
+```ts
+import type { HadarsOptions } from 'hadars';
+
+const config: HadarsOptions = {
+    entry: 'src/App.tsx',
+    // Cache every page by pathname for 60 seconds, skip authenticated requests
+    cache: (req) => req.cookies.session ? null : { key: req.pathname, ttl: 60_000 },
+};
+
+export default config;
+```
+
+## slim-react
+
+hadars ships its own lightweight React-compatible SSR renderer called **slim-react** (`src/slim-react/`). It replaces `react-dom/server` entirely on the server side - no `renderToStaticMarkup`, no `renderToPipeableStream`, no react-dom dependency at all.
+
+For server builds, rspack aliases `react` and `react/jsx-runtime` to slim-react, so your components and any libraries they import render through it automatically without any code changes.
+
+**What it does:**
+
+- Renders the full component tree to an HTML string with native `async/await` support - async components and hooks that return Promises are awaited directly without streaming workarounds
+- Implements the React Suspense protocol: when a component throws a Promise (e.g. from `useServerData` or a Suspense-enabled data library), slim-react awaits it and retries the tree automatically
+- Emits React-compatible hydration markers - `<!--$-->…<!--/$-->` for resolved Suspense boundaries, `<!-- -->` separators between adjacent text nodes - so `hydrateRoot` on the client works without mismatches
+- Supports `React.memo`, `React.forwardRef`, `React.lazy`, `Context.Provider`, `Context.Consumer`, and the React 18/19 element wire formats
+- Covers the full hook surface needed for SSR: `useState`, `useReducer`, `useContext`, `useRef`, `useMemo`, `useCallback`, `useId`, `useSyncExternalStore`, `use`, and more - all as lightweight SSR stubs
+
+**Why not react-dom/server?**
+
+`react-dom/server` cannot `await` arbitrary Promises thrown during render - it only handles Suspense via streaming and requires components to use `React.lazy` or Relay-style Suspense resources. slim-react's retry loop makes `useServerData` (and any hook that throws a Promise) work without wrapping every async component in a `<Suspense>` boundary.
 
 ## License
 

package/cli-lib.ts

@@ -99,17 +99,185 @@ dist/
 `import React from 'react';
 import { HadarsContext, HadarsHead, type HadarsApp } from 'hadars';
 
-const App: HadarsApp<{}> = ({ context }) => (
-  <HadarsContext context={context}>
-    <HadarsHead status={200}>
-      <title>My App</title>
-    </HadarsHead>
-    <main>
-      <h1>Hello from hadars!</h1>
-      <p>Edit <code>src/App.tsx</code> to get started.</p>
-    </main>
-  </HadarsContext>
-);
+const css = \`
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #0f0f13;
+    color: #e2e8f0;
+    min-height: 100vh;
+  }
+
+  .nav {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 1rem 2rem;
+    border-bottom: 1px solid #1e1e2e;
+  }
+  .nav-brand { font-weight: 700; font-size: 1.1rem; color: #a78bfa; letter-spacing: -0.02em; }
+  .nav-links { display: flex; gap: 1.5rem; }
+  .nav-links a { color: #94a3b8; text-decoration: none; font-size: 0.9rem; }
+  .nav-links a:hover { color: #e2e8f0; }
+
+  .hero {
+    text-align: center;
+    padding: 5rem 1rem 4rem;
+    max-width: 680px;
+    margin: 0 auto;
+  }
+  .hero-badge {
+    display: inline-block;
+    background: #1e1a2e;
+    border: 1px solid #4c1d95;
+    color: #a78bfa;
+    font-size: 0.75rem;
+    font-weight: 600;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+    padding: 0.3rem 0.8rem;
+    border-radius: 999px;
+    margin-bottom: 1.5rem;
+  }
+  .hero h1 {
+    font-size: clamp(2rem, 5vw, 3.25rem);
+    font-weight: 800;
+    letter-spacing: -0.03em;
+    line-height: 1.15;
+    margin-bottom: 1rem;
+  }
+  .hero h1 span { color: #a78bfa; }
+  .hero p {
+    font-size: 1.1rem;
+    color: #94a3b8;
+    line-height: 1.7;
+    margin-bottom: 2.5rem;
+  }
+  .hero-actions { display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap; }
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.65rem 1.4rem;
+    border-radius: 8px;
+    font-size: 0.9rem;
+    font-weight: 600;
+    cursor: pointer;
+    border: none;
+    transition: opacity 0.15s, transform 0.1s;
+    text-decoration: none;
+  }
+  .btn:hover { opacity: 0.85; transform: translateY(-1px); }
+  .btn:active { transform: translateY(0); }
+  .btn-primary { background: #7c3aed; color: #fff; }
+  .btn-ghost { background: #1e1e2e; color: #e2e8f0; border: 1px solid #2d2d3e; }
+
+  .features {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+    gap: 1rem;
+    max-width: 900px;
+    margin: 0 auto 4rem;
+    padding: 0 1.5rem;
+  }
+  .card {
+    background: #16161f;
+    border: 1px solid #1e1e2e;
+    border-radius: 12px;
+    padding: 1.5rem;
+  }
+  .card-icon { font-size: 1.5rem; margin-bottom: 0.75rem; }
+  .card h3 { font-size: 0.95rem; font-weight: 700; margin-bottom: 0.4rem; }
+  .card p { font-size: 0.85rem; color: #64748b; line-height: 1.6; }
+
+  .demo {
+    max-width: 480px;
+    margin: 0 auto 4rem;
+    padding: 0 1.5rem;
+    text-align: center;
+  }
+  .demo-box {
+    background: #16161f;
+    border: 1px solid #1e1e2e;
+    border-radius: 12px;
+    padding: 2rem;
+  }
+  .demo-box h2 { font-size: 0.8rem; font-weight: 600; color: #64748b; text-transform: uppercase; letter-spacing: 0.08em; margin-bottom: 1.25rem; }
+  .counter { font-size: 3.5rem; font-weight: 800; color: #a78bfa; letter-spacing: -0.04em; margin-bottom: 1.25rem; }
+  .demo-actions { display: flex; gap: 0.75rem; justify-content: center; }
+
+\`;
+
+const App: HadarsApp<{}> = ({ context }) => {
+  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 }} />
+      </HadarsHead>
+
+      <nav className="nav">
+        <span className="nav-brand">my-app</span>
+        <div className="nav-links">
+          <a href="https://github.com/dpostolachi/hadar" target="_blank" rel="noopener">github</a>
+        </div>
+      </nav>
+
+      <section className="hero">
+        <div className="hero-badge">built with hadars</div>
+        <h1>Ship <span>React apps</span><br />at full speed</h1>
+        <p>
+          SSR out of the box, zero config, instant hot-reload.
+          Edit <code>src/App.tsx</code> to get started.
+        </p>
+        <div className="hero-actions">
+          <button className="btn btn-primary" onClick={() => setCount(c => c + 1)}>
+            Try the counter ↓
+          </button>
+        </div>
+      </section>
+
+      <div className="features">
+        <div className="card">
+          <div className="card-icon">⚡</div>
+          <h3>Server-side rendering</h3>
+          <p>Pages render on the server and hydrate on the client — great for SEO and first paint.</p>
+        </div>
+        <div className="card">
+          <div className="card-icon">🔥</div>
+          <h3>Hot module reload</h3>
+          <p>Changes in <code>src/App.tsx</code> reflect instantly in the browser during development.</p>
+        </div>
+        <div className="card">
+          <div className="card-icon">📦</div>
+          <h3>Zero config</h3>
+          <p>One config file. Export a React component, run <code>hadars dev</code>, done.</p>
+        </div>
+        <div className="card">
+          <div className="card-icon">🗄️</div>
+          <h3>Server data hooks</h3>
+          <p>Use <code>useServerData</code> to fetch data on the server without extra round-trips.</p>
+        </div>
+      </div>
+
+      <div className="demo">
+        <div className="demo-box">
+          <h2>Client interactivity works</h2>
+          <div className="counter">{count}</div>
+          <div className="demo-actions">
+            <button className="btn btn-ghost" onClick={() => setCount(c => c - 1)}>− dec</button>
+            <button className="btn btn-primary" onClick={() => setCount(c => c + 1)}>+ inc</button>
+          </div>
+        </div>
+      </div>
+
+    </HadarsContext>
+  );
+};
 
 export default App;
 `,

package/dist/cli.js

@@ -892,15 +892,6 @@ var getConfigBase = (mode) => {
     },
     module: {
       rules: [
-        {
-          test: /\.mdx?$/,
-          use: [
-            {
-              loader: "@mdx-js/loader",
-              options: {}
-            }
-          ]
-        },
         {
           test: /\.css$/,
           use: ["postcss-loader"],
@@ -935,7 +926,7 @@ var getConfigBase = (mode) => {
                     react: {
                       runtime: "automatic",
                       development: isDev,
-                      refresh: isDev
+                      refresh: isDev && !isServerBuild
                     }
                   }
                 }
@@ -966,7 +957,7 @@ var getConfigBase = (mode) => {
                     react: {
                       runtime: "automatic",
                       development: isDev,
-                      refresh: isDev
+                      refresh: isDev && !isServerBuild
                     }
                   }
                 }
@@ -1028,12 +1019,15 @@ var buildCompilerConfig = (entry, opts, includeHotPlugin) => {
       }
     }
   }
-  const isServerBuild = Boolean(
+  if (opts.moduleRules && opts.moduleRules.length > 0) {
+    localConfig.module.rules.push(...opts.moduleRules);
+  }
+  const isServerBuild2 = Boolean(
     opts.output && typeof opts.output === "object" && (opts.output.library || String(opts.output.filename || "").includes("ssr"))
   );
   const slimReactIndex = pathMod.resolve(packageDir, "slim-react", "index.js");
   const slimReactJsx = pathMod.resolve(packageDir, "slim-react", "jsx-runtime.js");
-  const resolveAliases = isServerBuild ? {
+  const resolveAliases = isServerBuild2 ? {
     // Route all React imports to slim-react for SSR.
     react: slimReactIndex,
     "react/jsx-runtime": slimReactJsx,
@@ -1044,7 +1038,7 @@ var buildCompilerConfig = (entry, opts, includeHotPlugin) => {
     "@emotion/cache": path.resolve(process.cwd(), "node_modules", "@emotion", "cache"),
     "@emotion/styled": path.resolve(process.cwd(), "node_modules", "@emotion", "styled")
   } : void 0;
-  const externals = isServerBuild ? [
+  const externals = isServerBuild2 ? [
     // react / react-dom are replaced by slim-react via alias above — not external.
     // emotion should be external on server builds to avoid client/browser code
     "@emotion/react",
@@ -1065,9 +1059,9 @@ var buildCompilerConfig = (entry, opts, includeHotPlugin) => {
     extensions: [".tsx", ".ts", ".js", ".jsx"],
     alias: resolveAliases,
     // for server builds prefer the package "main"/"module" fields and avoid "browser" so we don't pick browser-specific entrypoints
-    mainFields: isServerBuild ? ["main", "module"] : ["browser", "module", "main"]
+    mainFields: isServerBuild2 ? ["main", "module"] : ["browser", "module", "main"]
   };
-  const optimization = !isServerBuild && !isDev ? {
+  const optimization = !isServerBuild2 && !isDev ? {
     moduleIds: "deterministic",
     splitChunks: {
       chunks: "all",
@@ -1127,7 +1121,7 @@ var buildCompilerConfig = (entry, opts, includeHotPlugin) => {
           });
         }
       },
-      isDev && new ReactRefreshPlugin(),
+      isDev && !isServerBuild2 && new ReactRefreshPlugin(),
       includeHotPlugin && isDev && new rspack.HotModuleReplacementPlugin(),
       ...extraPlugins
     ],
@@ -1143,7 +1137,7 @@ var buildCompilerConfig = (entry, opts, includeHotPlugin) => {
     // for client builds. SSR builds still need it for dynamic import() of exports.
     experiments: {
       ...localConfig.experiments || {},
-      outputModule: isServerBuild
+      outputModule: isServerBuild2
     },
     // Prevent rspack from watching its own build output — without this the
     // SSR watcher writing .hadars/index.ssr.js triggers the client compiler
@@ -1790,6 +1784,7 @@ var dev = async (options) => {
     mode: "development",
     swcPlugins: options.swcPlugins,
     define: options.define,
+    moduleRules: options.moduleRules,
     htmlTemplate: resolvedHtmlTemplate
   });
   const devServer = new RspackDevServer({
@@ -1826,7 +1821,8 @@ var dev = async (options) => {
     `--outFile=${SSR_FILENAME}`,
     `--base=${baseURL}`,
     ...options.swcPlugins ? [`--swcPlugins=${JSON.stringify(options.swcPlugins)}`] : [],
-    ...options.define ? [`--define=${JSON.stringify(options.define)}`] : []
+    ...options.define ? [`--define=${JSON.stringify(options.define)}`] : [],
+    ...options.moduleRules ? [`--moduleRules=${JSON.stringify(options.moduleRules)}`] : []
   ], { stdio: "pipe" });
   child.stdin?.end();
   const cleanupChild = () => {
@@ -2006,6 +2002,7 @@ var build = async (options) => {
       mode: "production",
       swcPlugins: options.swcPlugins,
       define: options.define,
+      moduleRules: options.moduleRules,
       optimization: options.optimization,
       htmlTemplate: resolvedHtmlTemplate
     }),
@@ -2021,7 +2018,8 @@ var build = async (options) => {
       target: "node",
       mode: "production",
       swcPlugins: options.swcPlugins,
-      define: options.define
+      define: options.define,
+      moduleRules: options.moduleRules
     })
   ]);
   await fs.rm(tmpFilePath);
@@ -2212,17 +2210,185 @@ dist/
   "src/App.tsx": () => `import React from 'react';
 import { HadarsContext, HadarsHead, type HadarsApp } from 'hadars';
 
-const App: HadarsApp<{}> = ({ context }) => (
-  <HadarsContext context={context}>
-    <HadarsHead status={200}>
-      <title>My App</title>
-    </HadarsHead>
-    <main>
-      <h1>Hello from hadars!</h1>
-      <p>Edit <code>src/App.tsx</code> to get started.</p>
-    </main>
-  </HadarsContext>
-);
+const css = \`
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #0f0f13;
+    color: #e2e8f0;
+    min-height: 100vh;
+  }
+
+  .nav {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 1rem 2rem;
+    border-bottom: 1px solid #1e1e2e;
+  }
+  .nav-brand { font-weight: 700; font-size: 1.1rem; color: #a78bfa; letter-spacing: -0.02em; }
+  .nav-links { display: flex; gap: 1.5rem; }
+  .nav-links a { color: #94a3b8; text-decoration: none; font-size: 0.9rem; }
+  .nav-links a:hover { color: #e2e8f0; }
+
+  .hero {
+    text-align: center;
+    padding: 5rem 1rem 4rem;
+    max-width: 680px;
+    margin: 0 auto;
+  }
+  .hero-badge {
+    display: inline-block;
+    background: #1e1a2e;
+    border: 1px solid #4c1d95;
+    color: #a78bfa;
+    font-size: 0.75rem;
+    font-weight: 600;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+    padding: 0.3rem 0.8rem;
+    border-radius: 999px;
+    margin-bottom: 1.5rem;
+  }
+  .hero h1 {
+    font-size: clamp(2rem, 5vw, 3.25rem);
+    font-weight: 800;
+    letter-spacing: -0.03em;
+    line-height: 1.15;
+    margin-bottom: 1rem;
+  }
+  .hero h1 span { color: #a78bfa; }
+  .hero p {
+    font-size: 1.1rem;
+    color: #94a3b8;
+    line-height: 1.7;
+    margin-bottom: 2.5rem;
+  }
+  .hero-actions { display: flex; gap: 1rem; justify-content: center; flex-wrap: wrap; }
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.65rem 1.4rem;
+    border-radius: 8px;
+    font-size: 0.9rem;
+    font-weight: 600;
+    cursor: pointer;
+    border: none;
+    transition: opacity 0.15s, transform 0.1s;
+    text-decoration: none;
+  }
+  .btn:hover { opacity: 0.85; transform: translateY(-1px); }
+  .btn:active { transform: translateY(0); }
+  .btn-primary { background: #7c3aed; color: #fff; }
+  .btn-ghost { background: #1e1e2e; color: #e2e8f0; border: 1px solid #2d2d3e; }
+
+  .features {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+    gap: 1rem;
+    max-width: 900px;
+    margin: 0 auto 4rem;
+    padding: 0 1.5rem;
+  }
+  .card {
+    background: #16161f;
+    border: 1px solid #1e1e2e;
+    border-radius: 12px;
+    padding: 1.5rem;
+  }
+  .card-icon { font-size: 1.5rem; margin-bottom: 0.75rem; }
+  .card h3 { font-size: 0.95rem; font-weight: 700; margin-bottom: 0.4rem; }
+  .card p { font-size: 0.85rem; color: #64748b; line-height: 1.6; }
+
+  .demo {
+    max-width: 480px;
+    margin: 0 auto 4rem;
+    padding: 0 1.5rem;
+    text-align: center;
+  }
+  .demo-box {
+    background: #16161f;
+    border: 1px solid #1e1e2e;
+    border-radius: 12px;
+    padding: 2rem;
+  }
+  .demo-box h2 { font-size: 0.8rem; font-weight: 600; color: #64748b; text-transform: uppercase; letter-spacing: 0.08em; margin-bottom: 1.25rem; }
+  .counter { font-size: 3.5rem; font-weight: 800; color: #a78bfa; letter-spacing: -0.04em; margin-bottom: 1.25rem; }
+  .demo-actions { display: flex; gap: 0.75rem; justify-content: center; }
+
+\`;
+
+const App: HadarsApp<{}> = ({ context }) => {
+  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 }} />
+      </HadarsHead>
+
+      <nav className="nav">
+        <span className="nav-brand">my-app</span>
+        <div className="nav-links">
+          <a href="https://github.com/dpostolachi/hadar" target="_blank" rel="noopener">github</a>
+        </div>
+      </nav>
+
+      <section className="hero">
+        <div className="hero-badge">built with hadars</div>
+        <h1>Ship <span>React apps</span><br />at full speed</h1>
+        <p>
+          SSR out of the box, zero config, instant hot-reload.
+          Edit <code>src/App.tsx</code> to get started.
+        </p>
+        <div className="hero-actions">
+          <button className="btn btn-primary" onClick={() => setCount(c => c + 1)}>
+            Try the counter \u2193
+          </button>
+        </div>
+      </section>
+
+      <div className="features">
+        <div className="card">
+          <div className="card-icon">\u26A1</div>
+          <h3>Server-side rendering</h3>
+          <p>Pages render on the server and hydrate on the client \u2014 great for SEO and first paint.</p>
+        </div>
+        <div className="card">
+          <div className="card-icon">\u{1F525}</div>
+          <h3>Hot module reload</h3>
+          <p>Changes in <code>src/App.tsx</code> reflect instantly in the browser during development.</p>
+        </div>
+        <div className="card">
+          <div className="card-icon">\u{1F4E6}</div>
+          <h3>Zero config</h3>
+          <p>One config file. Export a React component, run <code>hadars dev</code>, done.</p>
+        </div>
+        <div className="card">
+          <div className="card-icon">\u{1F5C4}\uFE0F</div>
+          <h3>Server data hooks</h3>
+          <p>Use <code>useServerData</code> to fetch data on the server without extra round-trips.</p>
+        </div>
+      </div>
+
+      <div className="demo">
+        <div className="demo-box">
+          <h2>Client interactivity works</h2>
+          <div className="counter">{count}</div>
+          <div className="demo-actions">
+            <button className="btn btn-ghost" onClick={() => setCount(c => c - 1)}>\u2212 dec</button>
+            <button className="btn btn-primary" onClick={() => setCount(c => c + 1)}>+ inc</button>
+          </div>
+        </div>
+      </div>
+
+    </HadarsContext>
+  );
+};
 
 export default App;
 `

package/dist/index.d.ts

@@ -111,6 +111,22 @@ interface HadarsOptions {
      * Note: inline styles are processed once at startup and are not live-reloaded.
      */
     htmlTemplate?: string;
+    /**
+     * Additional rspack module rules appended to the built-in rule set.
+     * Applied to both the client and the SSR bundle.
+     *
+     * Useful for loaders not included by default, such as `@mdx-js/loader`,
+     * `less-loader`, `yaml-loader`, etc.
+     *
+     * @example
+     * moduleRules: [
+     *   {
+     *     test: /\.mdx?$/,
+     *     use: [{ loader: '@mdx-js/loader' }],
+     *   },
+     * ]
+     */
+    moduleRules?: Record<string, any>[];
     /**
      * SSR response cache for `run()` mode. Has no effect in `dev()` mode.
      *

package/dist/ssr-watch.js

@@ -32,15 +32,6 @@ var getConfigBase = (mode) => {
     },
     module: {
       rules: [
-        {
-          test: /\.mdx?$/,
-          use: [
-            {
-              loader: "@mdx-js/loader",
-              options: {}
-            }
-          ]
-        },
         {
           test: /\.css$/,
           use: ["postcss-loader"],
@@ -75,7 +66,7 @@ var getConfigBase = (mode) => {
                     react: {
                       runtime: "automatic",
                       development: isDev,
-                      refresh: isDev
+                      refresh: isDev && !isServerBuild
                     }
                   }
                 }
@@ -106,7 +97,7 @@ var getConfigBase = (mode) => {
                     react: {
                       runtime: "automatic",
                       development: isDev,
-                      refresh: isDev
+                      refresh: isDev && !isServerBuild
                     }
                   }
                 }
@@ -168,12 +159,15 @@ var buildCompilerConfig = (entry2, opts, includeHotPlugin) => {
       }
     }
   }
-  const isServerBuild = Boolean(
+  if (opts.moduleRules && opts.moduleRules.length > 0) {
+    localConfig.module.rules.push(...opts.moduleRules);
+  }
+  const isServerBuild2 = Boolean(
     opts.output && typeof opts.output === "object" && (opts.output.library || String(opts.output.filename || "").includes("ssr"))
   );
   const slimReactIndex = pathMod.resolve(packageDir, "slim-react", "index.js");
   const slimReactJsx = pathMod.resolve(packageDir, "slim-react", "jsx-runtime.js");
-  const resolveAliases = isServerBuild ? {
+  const resolveAliases = isServerBuild2 ? {
     // Route all React imports to slim-react for SSR.
     react: slimReactIndex,
     "react/jsx-runtime": slimReactJsx,
@@ -184,7 +178,7 @@ var buildCompilerConfig = (entry2, opts, includeHotPlugin) => {
     "@emotion/cache": path.resolve(process.cwd(), "node_modules", "@emotion", "cache"),
     "@emotion/styled": path.resolve(process.cwd(), "node_modules", "@emotion", "styled")
   } : void 0;
-  const externals = isServerBuild ? [
+  const externals = isServerBuild2 ? [
     // react / react-dom are replaced by slim-react via alias above — not external.
     // emotion should be external on server builds to avoid client/browser code
     "@emotion/react",
@@ -205,9 +199,9 @@ var buildCompilerConfig = (entry2, opts, includeHotPlugin) => {
     extensions: [".tsx", ".ts", ".js", ".jsx"],
     alias: resolveAliases,
     // for server builds prefer the package "main"/"module" fields and avoid "browser" so we don't pick browser-specific entrypoints
-    mainFields: isServerBuild ? ["main", "module"] : ["browser", "module", "main"]
+    mainFields: isServerBuild2 ? ["main", "module"] : ["browser", "module", "main"]
   };
-  const optimization = !isServerBuild && !isDev ? {
+  const optimization = !isServerBuild2 && !isDev ? {
     moduleIds: "deterministic",
     splitChunks: {
       chunks: "all",
@@ -267,7 +261,7 @@ var buildCompilerConfig = (entry2, opts, includeHotPlugin) => {
           });
         }
       },
-      isDev && new ReactRefreshPlugin(),
+      isDev && !isServerBuild2 && new ReactRefreshPlugin(),
       includeHotPlugin && isDev && new rspack.HotModuleReplacementPlugin(),
       ...extraPlugins
     ],
@@ -283,7 +277,7 @@ var buildCompilerConfig = (entry2, opts, includeHotPlugin) => {
     // for client builds. SSR builds still need it for dynamic import() of exports.
     experiments: {
       ...localConfig.experiments || {},
-      outputModule: isServerBuild
+      outputModule: isServerBuild2
     },
     // Prevent rspack from watching its own build output — without this the
     // SSR watcher writing .hadars/index.ssr.js triggers the client compiler
@@ -360,6 +354,7 @@ var outFile = argv["outFile"] || "index.ssr.js";
 var base = argv["base"] || "";
 var swcPlugins = argv["swcPlugins"] ? JSON.parse(argv["swcPlugins"]) : void 0;
 var define = argv["define"] ? JSON.parse(argv["define"]) : void 0;
+var moduleRules = argv["moduleRules"] ? JSON.parse(argv["moduleRules"]) : void 0;
 if (!entry) {
   console.error("ssr-watch: missing --entry argument");
   process.exit(1);
@@ -381,6 +376,7 @@ if (!entry) {
       watch: true,
       swcPlugins,
       define,
+      moduleRules,
       onChange: () => {
         console.log("ssr-watch: SSR rebuilt");
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadars",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Minimal SSR framework for React — rspack, HMR, TypeScript, Bun/Node/Deno",
   "module": "./dist/index.js",
   "type": "module",
@@ -77,7 +77,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@mdx-js/loader": "^3.1.1",
     "@svgr/webpack": "^8.1.0",
     "postcss": "^8.5.8",
     "postcss-load-config": "^6.0.1",

package/src/build.ts

@@ -507,6 +507,7 @@ export const dev = async (options: HadarsRuntimeOptions) => {
         mode: 'development',
         swcPlugins: options.swcPlugins,
         define: options.define,
+        moduleRules: options.moduleRules,
         htmlTemplate: resolvedHtmlTemplate,
     });
 
@@ -554,6 +555,7 @@ export const dev = async (options: HadarsRuntimeOptions) => {
         `--base=${baseURL}`,
         ...(options.swcPlugins ? [`--swcPlugins=${JSON.stringify(options.swcPlugins)}`] : []),
         ...(options.define ? [`--define=${JSON.stringify(options.define)}`] : []),
+        ...(options.moduleRules ? [`--moduleRules=${JSON.stringify(options.moduleRules)}`] : []),
     ], { stdio: 'pipe' });
     child.stdin?.end();
 
@@ -747,6 +749,7 @@ export const build = async (options: HadarsRuntimeOptions) => {
             mode: 'production',
             swcPlugins: options.swcPlugins,
             define: options.define,
+            moduleRules: options.moduleRules,
             optimization: options.optimization,
             htmlTemplate: resolvedHtmlTemplate,
         }),
@@ -763,6 +766,7 @@ export const build = async (options: HadarsRuntimeOptions) => {
             mode: 'production',
             swcPlugins: options.swcPlugins,
             define: options.define,
+            moduleRules: options.moduleRules,
         }),
     ]);
     await fs.rm(tmpFilePath);

package/src/ssr-watch.ts

@@ -21,6 +21,7 @@ const outFile = argv['outFile'] || 'index.ssr.js';
 const base = argv['base'] || '';
 const swcPlugins = argv['swcPlugins'] ? JSON.parse(argv['swcPlugins']) : undefined;
 const define = argv['define'] ? JSON.parse(argv['define']) : undefined;
+const moduleRules = argv['moduleRules'] ? JSON.parse(argv['moduleRules']) : undefined;
 
 if (!entry) {
   console.error('ssr-watch: missing --entry argument');
@@ -44,6 +45,7 @@ if (!entry) {
       watch: true,
       swcPlugins,
       define,
+      moduleRules,
       onChange: () => {
         console.log('ssr-watch: SSR rebuilt');
       }

package/src/types/hadars.ts

@@ -111,6 +111,22 @@ export interface HadarsOptions {
      * Note: inline styles are processed once at startup and are not live-reloaded.
      */
     htmlTemplate?: string;
+    /**
+     * Additional rspack module rules appended to the built-in rule set.
+     * Applied to both the client and the SSR bundle.
+     *
+     * Useful for loaders not included by default, such as `@mdx-js/loader`,
+     * `less-loader`, `yaml-loader`, etc.
+     *
+     * @example
+     * moduleRules: [
+     *   {
+     *     test: /\.mdx?$/,
+     *     use: [{ loader: '@mdx-js/loader' }],
+     *   },
+     * ]
+     */
+    moduleRules?: Record<string, any>[];
     /**
      * SSR response cache for `run()` mode. Has no effect in `dev()` mode.
      *

package/src/utils/rspack.ts

@@ -38,16 +38,6 @@ const getConfigBase = (mode: "development" | "production"): Omit<Configuration,
         },
         module: {
             rules: [
-                {
-                    test: /\.mdx?$/,
-                    use: [
-                    {
-                        loader: '@mdx-js/loader',
-                        options: {
-                        },
-                    },
-                    ],
-                },
                 {
                     test: /\.css$/,
                     use: ["postcss-loader"],
@@ -82,7 +72,7 @@ const getConfigBase = (mode: "development" | "production"): Omit<Configuration,
                                         react: {
                                             runtime: "automatic",
                                             development: isDev,
-                                            refresh: isDev,
+                                            refresh: isDev && !isServerBuild,
                                         },
                                     },
                                 },
@@ -113,7 +103,7 @@ const getConfigBase = (mode: "development" | "production"): Omit<Configuration,
                                         react: {
                                             runtime: "automatic",
                                             development: isDev,
-                                            refresh: isDev,
+                                            refresh: isDev && !isServerBuild,
                                         },
                                     },
                                 },
@@ -142,6 +132,8 @@ interface EntryOptions {
     base?: string;
     // optional rspack optimization overrides (production client builds only)
     optimization?: Record<string, unknown>;
+    // additional module rules appended after the built-in rules
+    moduleRules?: Record<string, any>[];
 }
 
 const buildCompilerConfig = (
@@ -207,6 +199,10 @@ const buildCompilerConfig = (
         }
     }
 
+    if (opts.moduleRules && opts.moduleRules.length > 0) {
+        localConfig.module.rules.push(...opts.moduleRules);
+    }
+
     // For server (SSR) builds we should avoid bundling react/react-dom so
     // the runtime uses the same React instance as the host. If the output
     // is a library/module (i.e. `opts.output.library` present or filename
@@ -330,7 +326,7 @@ const buildCompilerConfig = (
                     });
                 },
             },
-            isDev && new ReactRefreshPlugin(),
+            isDev && !isServerBuild && new ReactRefreshPlugin(),
             includeHotPlugin && isDev && new rspack.HotModuleReplacementPlugin(),
             ...extraPlugins,
         ],