hadars 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ninety contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# hadars
+
+A minimal server-side rendering framework for React built on [rspack](https://rspack.dev). Runs on Bun, Node.js, and Deno.
+
+## Install
+
+```bash
+npm install hadars
+```
+
+## Quick start
+
+**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;
+```
+
+**src/App.tsx**
+```tsx
+import React from 'react';
+import { HadarsContext, HadarsHead, type HadarsApp, type HadarsRequest } from 'hadars';
+
+interface Props { user: { name: string } }
+
+const App: HadarsApp<Props> = ({ user, context }) => (
+    <HadarsContext context={context}>
+        <HadarsHead status={200}>
+            <title>Hello {user.name}</title>
+        </HadarsHead>
+        <h1>Hello, {user.name}!</h1>
+    </HadarsContext>
+);
+
+export const getInitProps = async (req: HadarsRequest): Promise<Props> => ({
+    user: await db.getUser(req.cookies.session),
+});
+
+export default App;
+```
+
+## CLI
+
+After installing hadars the `hadars` (Node.js) and `hadars-bun` (Bun) binaries are available:
+
+```bash
+# Development server with React Fast Refresh HMR
+hadars dev
+hadars-bun dev     # Bun — runs TypeScript directly, no build step
+
+# Production build (client + SSR bundles compiled in parallel)
+hadars build
+
+# Serve the production build
+hadars run         # multi-core when workers > 1
+```
+
+## 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
+- **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
+
+## Data lifecycle hooks
+
+| Hook | Runs on | Purpose |
+|---|---|---|
+| `getInitProps` | server | Fetch server-side data from the `HadarsRequest` |
+| `getAfterRenderProps` | server | Inspect the rendered HTML (e.g. extract critical CSS) |
+| `getFinalProps` | server | Strip server-only fields before props are serialised to the client |
+| `getClientProps` | client | Enrich props with browser-only data (localStorage, device APIs) |
+
+## HadarsOptions
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `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) |
+| `wsPath` | `string` | `"/ws"` | Path that triggers WebSocket upgrade |
+| `streaming` | `boolean` | `false` | Set to `true` to use `renderToReadableStream` (streaming SSR) instead of the default `renderToString` |
+
+## Local build
+
+```bash
+npm install
+npm run build:all
+```
+
+## Publishing
+
+1. Update `version`, `repository`, `license` in `package.json`
+2. `npm login`
+3. `npm publish`
+
+## License
+
+MIT

package/cli-bun.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+import { runCli } from './cli-lib'
+
+runCli(process.argv).catch((err) => {
+  console.error(err)
+  // When Bun runs a script, allow non-zero exit codes to propagate
+  try {
+    process.exit(1)
+  } catch (_) {
+    // Some Bun environments may not allow process.exit; just rethrow
+    throw err
+  }
+})

package/cli-lib.ts

@@ -0,0 +1,203 @@
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { resolve, join } from 'node:path'
+import * as Hadars from './src/build'
+import type { HadarsOptions } from './src/types/ninety'
+
+const SUPPORTED = ['hadars.config.js', 'hadars.config.mjs', 'hadars.config.cjs', 'hadars.config.ts']
+
+function findConfig(cwd: string): string | null {
+  for (const name of SUPPORTED) {
+    const p = resolve(cwd, name)
+    if (existsSync(p)) return p
+  }
+  return null
+}
+
+async function dev(config: HadarsOptions) {
+    await Hadars.dev({
+      ...config,
+      baseURL: '',
+      mode: 'development',
+    });
+}
+
+async function build(config: HadarsOptions) {
+    await Hadars.build({
+      ...config,
+      mode: 'production',
+    });
+}
+
+async function run(config: HadarsOptions) {
+    await Hadars.run({
+      ...config,
+      mode: 'production',
+    });
+}
+
+async function loadConfig(configPath: string): Promise<HadarsOptions> {
+  const url = `file://${configPath}`
+  const mod = await import(url)
+  return (mod && (mod.default ?? mod)) as HadarsOptions
+}
+
+// ── hadars new ────────────────────────────────────────────────────────────────
+
+const TEMPLATES: Record<string, (name: string) => string> = {
+  'package.json': (name: string) => JSON.stringify({
+    name,
+    version: '0.1.0',
+    type: 'module',
+    private: true,
+    scripts: {
+      dev:   'hadars dev',
+      build: 'hadars build',
+      start: 'hadars run',
+    },
+    dependencies: {
+      'hadars': 'latest',
+      react:      '^19.0.0',
+      'react-dom':'^19.0.0',
+    },
+  }, null, 2) + '\n',
+
+  'hadars.config.ts': () =>
+`import type { HadarsOptions } from 'hadars';
+
+const config: HadarsOptions = {
+  entry: 'src/App.tsx',
+  port: 3000,
+};
+
+export default config;
+`,
+
+  'tsconfig.json': () => JSON.stringify({
+    compilerOptions: {
+      lib:                        ['ESNext', 'DOM'],
+      target:                     'ESNext',
+      module:                     'Preserve',
+      moduleDetection:            'force',
+      jsx:                        'react-jsx',
+      moduleResolution:           'bundler',
+      allowImportingTsExtensions: true,
+      verbatimModuleSyntax:       true,
+      noEmit:                     true,
+      strict:                     true,
+      skipLibCheck:               true,
+    },
+  }, null, 2) + '\n',
+
+  '.gitignore': () =>
+`node_modules/
+.hadars/
+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>
+);
+
+export default App;
+`,
+}
+
+async function createProject(name: string, cwd: string): Promise<void> {
+  const dir = resolve(cwd, name)
+
+  if (existsSync(dir)) {
+    console.error(`Directory already exists: ${dir}`)
+    process.exit(1)
+  }
+
+  console.log(`Creating hadars project in ${dir}`)
+
+  await mkdir(join(dir, 'src'), { recursive: true })
+
+  for (const [file, template] of Object.entries(TEMPLATES)) {
+    const content = template(name)
+    await writeFile(join(dir, file), content, 'utf-8')
+    console.log(`  created  ${file}`)
+  }
+
+  console.log(`
+Done! Next steps:
+
+  cd ${name}
+  npm install       # or: bun install / pnpm install
+  npm run dev       # or: bun run dev
+`)
+}
+
+// ── CLI entry ─────────────────────────────────────────────────────────────────
+
+function usage(): void {
+  console.log('Usage: hadars <new <name> | dev | build | run>')
+}
+
+export async function runCli(argv: string[], cwd = process.cwd()): Promise<void> {
+  const cmd = argv[2]
+
+  if (cmd === 'new') {
+    const name = argv[3]
+    if (!name) {
+      console.error('Usage: hadars new <project-name>')
+      process.exit(1)
+    }
+    try {
+      await createProject(name, cwd)
+    } catch (err: any) {
+      console.error('Failed to create project:', err?.message ?? err)
+      process.exit(2)
+    }
+    return
+  }
+
+  if (!cmd || !['dev', 'build', 'run'].includes(cmd)) {
+    usage()
+    process.exit(1)
+  }
+
+  const configPath = findConfig(cwd)
+  if (!configPath) {
+    console.log(`No hadars.config.* found in ${cwd}`)
+    console.log('Proceeding with default behavior (no config)')
+    return
+  }
+
+  try {
+    const cfg = await loadConfig(configPath)
+    console.log(`Loaded config from ${configPath}`)
+    switch (cmd) {
+        case 'dev':
+            console.log('Starting development server...')
+            await dev(cfg);
+            break;
+        case 'build':
+            console.log('Building project...')
+            await build(cfg);
+            console.log('Build complete')
+            process.exit(0)
+        case 'run':
+            console.log('Running project...')
+            await run(cfg);
+            break;
+    }
+  } catch (err: any) {
+    console.error('Failed to load config:', err?.message ?? err)
+    process.exit(2)
+  }
+}

package/cli.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { runCli } from './cli-lib'
+
+runCli(process.argv).catch((err) => {
+  console.error(err)
+  // When Bun runs a script, allow non-zero exit codes to propagate
+  try {
+    process.exit(1)
+  } catch (_) {
+    // Some Bun environments may not allow process.exit; just rethrow
+    throw err
+  }
+})