nukejs 0.0.1 → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NukeJS
+
+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,529 @@
+# ☢️ NukeJS
+
+A **minimal**, opinionated full-stack React framework on Node.js that server-renders everything and hydrates only interactive parts.
+
+```
+npm create nuke
+```
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Getting Started](#getting-started)
+- [Project Structure](#project-structure)
+- [Pages & Routing](#pages--routing)
+- [Layouts](#layouts)
+- [Client Components](#client-components)
+- [API Routes](#api-routes)
+- [Middleware](#middleware)
+- [Static Files](#static-files)
+- [useHtml() — Head Management](#usehtml--head-management)
+- [Configuration](#configuration)
+- [Building & Deploying](#building--deploying)
+
+## Overview
+
+NukeJS gives you:
+
+| Feature | Description |
+|---|---|
+| **File-based routing** | Pages in `app/pages/`, API in `server/` |
+| **Server-side rendering** | All pages rendered to HTML on the server |
+| **Partial hydration** | Only `"use client"` components download JS |
+| **SPA navigation** | Client-side page transitions after first load |
+| **Hot module replacement** | Instant page updates during development |
+| **Zero config** | Works out of the box; `nuke.config.ts` for overrides |
+| **Deploy anywhere** | Node.js or Vercel serverless |
+
+### The core idea
+
+Most pages don't need JavaScript. NukeJS renders your entire React tree to HTML on the server, and only ships JavaScript for components explicitly marked `"use client"`. Everything else stays server-only — no hydration cost, no JS bundle for static content.
+
+```tsx
+// app/pages/index.tsx — Server component (zero JS sent to browser)
+export default async function Home() {
+  const posts = await db.getPosts(); // runs on server only
+  return (
+    <main>
+      <h1>Blog</h1>
+      {posts.map(p => <PostCard key={p.id} post={p} />)}
+      <LikeButton postId={posts[0].id} />  {/* ← this one is interactive */}
+    </main>
+  );
+}
+```
+
+```tsx
+// app/components/LikeButton.tsx — Client component (JS downloaded)
+"use client";
+import { useState } from 'react';
+
+export default function LikeButton({ postId }: { postId: string }) {
+  const [liked, setLiked] = useState(false);
+  return <button onClick={() => setLiked(!liked)}>{liked ? '❤️' : '🤍'}</button>;
+}
+```
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- React 19+
+- esbuild (peer dependency)
+
+### Installation
+
+```bash
+npm create nuke
+```
+
+### Running the dev server
+
+```bash
+npm run dev
+```
+
+The server starts on port 3000 by default (auto-increments if in use).
+
+---
+
+## Project Structure
+
+```
+my-app/
+├── app/
+│   ├── pages/              # Page components (file-based routing)
+│   │   ├── layout.tsx      # Root layout (wraps every page)
+│   │   ├── index.tsx       # → /
+│   │   ├── about.tsx       # → /about
+│   │   └── blog/
+│   │       ├── layout.tsx  # Blog section layout
+│   │       ├── index.tsx   # → /blog
+│   │       └── [slug].tsx  # → /blog/:slug
+│   ├── components/         # Shared components (not routed)
+│   └── public/             # Static files served at root (e.g. /favicon.ico)
+├── server/                 # API route handlers
+│   ├── users/
+│   │   ├── index.ts        # → GET/POST /users
+│   │   └── [id].ts         # → GET/PUT/DELETE /users/:id
+│   └── auth.ts             # → /auth
+├── middleware.ts           # (optional) global request middleware
+├── nuke.config.ts          # (optional) configuration
+└── package.json
+```
+
+---
+
+## Pages & Routing
+
+### Basic pages
+
+Each `.tsx` file in `app/pages/` maps to a URL route:
+
+| File | URL |
+|---|---|
+| `index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `blog/index.tsx` | `/blog` |
+| `blog/[slug].tsx` | `/blog/:slug` |
+| `docs/[...path].tsx` | `/docs/*` (catch-all) |
+| `files/[[...path]].tsx` | `/files` or `/files/*` (optional) |
+
+### Page component
+
+A page exports a default React component. It may be async (runs on the server).
+
+```tsx
+// app/pages/blog/[slug].tsx
+export default async function BlogPost({ slug }: { slug: string }) {
+  const post = await fetchPost(slug);
+  return (
+    <article>
+      <h1>{post.title}</h1>
+      <p>{post.content}</p>
+    </article>
+  );
+}
+```
+
+Route params are passed as props to the component.
+
+### Catch-all routes
+
+```tsx
+// app/pages/docs/[...path].tsx
+export default function Docs({ path }: { path: string[] }) {
+  // path = ['getting-started', 'installation'] for /docs/getting-started/installation
+  return <DocViewer segments={path} />;
+}
+```
+
+### Route specificity
+
+When multiple routes could match a URL, the most specific one wins:
+
+```
+/users/profile  → users/profile.tsx   (static, wins)
+/users/42       → users/[id].tsx      (dynamic)
+/users/a/b/c    → users/[...rest].tsx (catch-all)
+```
+
+---
+
+## Layouts
+
+Place a `layout.tsx` alongside your pages to wrap a group of routes.
+
+```tsx
+// app/pages/layout.tsx — Wraps every page
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div>
+      <Nav />
+      <main>{children}</main>
+      <Footer />
+    </div>
+  );
+}
+```
+
+Layouts nest automatically. A page at `blog/[slug].tsx` gets wrapped by both `layout.tsx` (root) and `blog/layout.tsx` (blog section).
+
+### Title templates in layouts
+
+```tsx
+// app/pages/layout.tsx
+import { useHtml } from 'nukejs';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  useHtml({ title: (prev) => `${prev} | Acme Corp` });
+  return <>{children}</>;
+}
+
+// app/pages/about.tsx
+export default function About() {
+  useHtml({ title: 'About Us' });
+  // Final title: "About Us | Acme Corp"
+  return <h1>About</h1>;
+}
+```
+
+---
+
+## Client Components
+
+Add `"use client"` as the very first line of any component file to make it a **client component**. NukeJS will:
+
+1. Bundle that file separately and serve it as `/__client-component/<id>.js`
+2. Render a `<span data-hydrate-id="…">` placeholder in the server HTML
+3. Hydrate the placeholder with React in the browser
+
+```tsx
+"use client";
+import { useState, useEffect } from 'react';
+
+export default function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = useState(initial);
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => setCount(c => c + 1)}>+</button>
+    </div>
+  );
+}
+```
+
+### Rules for client components
+
+- The `"use client"` directive must be the **first non-comment line**
+- The component must have a **named default export** (NukeJS uses the function name to match props during hydration)
+- Props must be **JSON-serializable** (no functions, no class instances)
+- React elements passed as props are supported (serialized and reconstructed)
+
+### Passing children to client components
+
+Children and other React elements can be passed as props — NukeJS serializes them at render time:
+
+```tsx
+// Server component
+<Modal>
+  <p>This content is from the server</p>
+</Modal>
+
+// Modal is a "use client" component; its children are serialized as
+// { __re: 'html', tag: 'p', props: { children: 'This content...' } }
+// and reconstructed in the browser before mounting.
+```
+
+---
+
+## API Routes
+
+Export named HTTP method handlers from `.ts` files in your `server/` directory.
+
+```ts
+// server/users/index.ts
+import type { ApiRequest, ApiResponse } from 'nukejs';
+
+export async function GET(req: ApiRequest, res: ApiResponse) {
+  const users = await db.getUsers();
+  res.json(users);
+}
+
+export async function POST(req: ApiRequest, res: ApiResponse) {
+  const user = await db.createUser(req.body);
+  res.json(user, 201);
+}
+```
+
+```ts
+// server/users/[id].ts
+export async function GET(req: ApiRequest, res: ApiResponse) {
+  const { id } = req.params as { id: string };
+  const user = await db.getUser(id);
+  if (!user) { res.json({ error: 'Not found' }, 404); return; }
+  res.json(user);
+}
+
+export async function DELETE(req: ApiRequest, res: ApiResponse) {
+  await db.deleteUser(req.params!.id as string);
+  res.status(204).end();
+}
+```
+
+### Request object
+
+| Property | Type | Description |
+|---|---|---|
+| `req.body` | `any` | Parsed JSON body (or raw string), up to 10 MB |
+| `req.params` | `Record<string, string \| string[]>` | Dynamic route segments |
+| `req.query` | `Record<string, string>` | URL search params |
+| `req.method` | `string` | HTTP method |
+| `req.headers` | `IncomingHttpHeaders` | Request headers |
+
+### Response object
+
+| Method | Description |
+|---|---|
+| `res.json(data, status?)` | Send a JSON response (default status 200) |
+| `res.status(code)` | Set status code and return `res` for chaining |
+| `res.setHeader(name, value)` | Set a response header |
+| `res.end(body?)` | Send raw response |
+
+---
+
+## Middleware
+
+Create `middleware.ts` in your project root to intercept every request before routing:
+
+```ts
+// middleware.ts
+import type { IncomingMessage, ServerResponse } from 'http';
+
+export default async function middleware(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  // Logging
+  console.log(`${req.method} ${req.url}`);
+
+  // Auth guard
+  if (req.url?.startsWith('/admin') && !isAuthenticated(req)) {
+    res.statusCode = 401;
+    res.end('Unauthorized');
+    return; // End response to halt further processing
+  }
+
+  // Header injection (let request continue without ending it)
+  res.setHeader('X-Powered-By', 'nukejs');
+}
+```
+
+If `res.end()` (or `res.json()`) is called, NukeJS stops processing and does not handle the request through routing. If middleware returns without ending the response, the request continues to API routes or SSR.
+
+---
+
+## Static Files
+
+Place any file in `app/public/` and it will be served directly at its path relative to that directory — no route file needed.
+
+```
+app/public/
+├── favicon.ico        → GET /favicon.ico
+├── robots.txt         → GET /robots.txt
+├── logo.png           → GET /logo.png
+└── fonts/
+    └── inter.woff2    → GET /fonts/inter.woff2
+```
+
+Every file type is served with the correct `Content-Type` automatically (images, fonts, CSS, video, audio, JSON, WASM, etc.).
+
+Reference public files directly in your components:
+
+```tsx
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <link rel="icon" href="/favicon.ico" />
+      <img src="/logo.png" alt="Logo" />
+      {children}
+    </>
+  );
+}
+```
+
+### Deployment behaviour
+
+| Environment | How public files are served |
+|---|---|
+| `nuke dev` | Served by the built-in middleware before any API or SSR routing |
+| `nuke build` (Node) | Copied to `dist/static/` and served by the production HTTP server |
+| `nuke build` (Vercel) | Copied to `.vercel/output/static/` — served by Vercel's CDN, no function invocation |
+
+On Vercel, public files receive the same zero-latency CDN treatment as `__react.js` and `__n.js`.
+
+---
+
+## useHtml() — Head Management
+
+The `useHtml()` hook works in both server components and client components to control the document head.
+
+```tsx
+import { useHtml } from 'nukejs';
+
+export default function Page() {
+  useHtml({
+    title: 'My Page',
+
+    meta: [
+      { name: 'description', content: 'Page description' },
+      { property: 'og:title', content: 'My Page' },
+    ],
+
+    link: [
+      { rel: 'canonical', href: 'https://example.com/page' },
+      { rel: 'stylesheet', href: '/styles.css' },
+    ],
+
+    htmlAttrs: { lang: 'en', class: 'dark' },
+    bodyAttrs: { class: 'page-home' },
+  });
+
+  return <main>...</main>;
+}
+```
+
+### Title resolution order
+
+When both a layout and a page call `useHtml({ title })`, they are resolved in this order:
+
+```
+Layout: useHtml({ title: (prev) => `${prev} | Site` })
+Page:   useHtml({ title: 'Home' })
+Result: "Home | Site"
+```
+
+The page title always serves as the base value; layout functions wrap it outward.
+
+---
+
+## Configuration
+
+Create `nuke.config.ts` in your project root:
+
+```ts
+// nuke.config.ts
+export default {
+  // Directory containing API route files (default: './server')
+  serverDir: './server',
+
+  // Port for the dev server (default: 3000, auto-increments if in use)
+  port: 3000,
+
+  // Logging verbosity
+  // false    — silent (default)
+  // 'error'  — errors only
+  // 'info'   — startup messages + errors
+  // true     — verbose (all debug output)
+  debug: false,
+};
+```
+
+---
+
+## Link Component & Navigation
+
+Use the built-in `<Link>` component for client-side navigation (no full page reload):
+
+```tsx
+import { Link } from 'nukejs';
+
+export default function Nav() {
+  return (
+    <nav>
+      <Link href="/">Home</Link>
+      <Link href="/about">About</Link>
+      <Link href="/blog">Blog</Link>
+    </nav>
+  );
+}
+```
+
+### useRouter
+
+```tsx
+"use client";
+import { useRouter } from 'nukejs';
+
+export default function SearchForm() {
+  const router = useRouter();
+  return (
+    <button onClick={() => router.push('/results?q=nuke')}>
+      Search
+    </button>
+  );
+}
+```
+
+---
+
+## Building & Deploying
+
+### Node.js server
+
+```bash
+npm run build       # builds to dist/
+node dist/index.mjs # starts the production server
+```
+
+The build output:
+
+```
+dist/
+├── api/            # Bundled API route handlers (.mjs)
+├── pages/          # Bundled page handlers (.mjs)
+├── static/
+│   ├── __react.js          # Bundled React runtime
+│   ├── __n.js              # NukeJS client runtime
+│   ├── __client-component/ # Bundled "use client" component files
+│   └── <app/public files>  # Copied from app/public/ at build time
+├── manifest.json   # Route dispatch table
+└── index.mjs       # HTTP server entry point
+```
+
+### Vercel
+Just import the code from GitHub.
+
+### Environment variables
+
+| Variable | Description |
+|---|---|
+| `ENVIRONMENT=production` | Disables HMR and file watching |
+| `PORT` | Port for the production server |
+
+## License
+
+MIT

package/bin/index.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import fs from 'fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const distDir = path.join(__dirname, '../dist');
+const srcDir = path.join(__dirname, '../src');
+
+const arg = process.argv[2];
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function spawnWith(bin, args, extraEnv = {}) {
+  const child = spawn(bin, args, {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    env: { ...process.env, ...extraEnv },
+  });
+  child.on('exit', (code) => process.exit(code ?? 0));
+}
+
+const isWindows = process.platform === 'win32';
+
+function resolveBin(name) {
+  // On Windows, .bin/ entries are .cmd wrappers — must include the extension
+  const candidates = isWindows ? [name + '.cmd', name + '.ps1', name] : [name];
+
+  const searchDirs = [
+    path.join(process.cwd(), 'node_modules', '.bin'),       // user's project
+    path.join(__dirname, '..', 'node_modules', '.bin'),     // nukejs's own deps
+  ];
+
+  for (const dir of searchDirs) {
+    for (const candidate of candidates) {
+      const full = path.join(dir, candidate);
+      if (fs.existsSync(full)) return full;
+    }
+  }
+
+  // last resort: rely on PATH (works if tsx is installed globally)
+  return isWindows ? name + '.cmd' : name;
+}
+
+function runWithNode(scriptPath, extraEnv = {}) {
+  if (!fs.existsSync(scriptPath)) {
+    console.error(`\n  ✖  Cannot find ${path.relative(process.cwd(), scriptPath)}`);
+    console.error(`     Run "nuke build" first.\n`);
+    process.exit(1);
+  }
+  spawnWith(process.execPath, [scriptPath], extraEnv);
+}
+
+const RESTART_CODE = 75;
+
+function runWithTsx(scriptPath, extraEnv = {}) {
+  if (!fs.existsSync(scriptPath)) {
+    console.error(`\n  ✖  Cannot find ${path.relative(process.cwd(), scriptPath)}`);
+    console.error(`     Is the nukejs package intact?\n`);
+    process.exit(1);
+  }
+
+  const tsx = resolveBin('tsx');
+
+  function launch() {
+    // On Windows, .bin/ entries are .cmd wrappers which cannot be spawned
+    // directly — they require the shell to interpret them.  Rather than
+    // setting shell:true (which triggers DEP0190 and passes args through an
+    // unescaped shell string), we invoke cmd.exe explicitly with /c so the
+    // arguments remain as a proper array and are never concatenated by Node.
+    const [bin, args] = isWindows && tsx.endsWith('.cmd')
+      ? ['cmd.exe', ['/c', tsx, scriptPath]]
+      : [tsx, [scriptPath]];
+
+    const child = spawn(bin, args, {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+      env: { ...process.env, ...extraEnv },
+      // shell is always false — cmd.exe /c handles .cmd dispatch on Windows,
+      // and Unix never needed it.
+      shell: false,
+    });
+    child.on('exit', (code) => {
+      if (code === RESTART_CODE) {
+        console.log('\n  ↺  Restarting server...\n');
+        launch();
+      } else {
+        process.exit(code ?? 0);
+      }
+    });
+  }
+
+  launch();
+}
+
+// ── commands ──────────────────────────────────────────────────────────────────
+
+if (!arg || arg === 'dev') {
+  // nuke | nuke dev  →  prefer src/app.ts (monorepo / local dev),
+  //                     fall back to dist/app.js (installed package)
+  const srcEntry = path.join(srcDir, 'app.ts');
+  const distEntry = path.join(distDir, 'app.js');
+  const devScript = fs.existsSync(srcEntry) ? srcEntry : distEntry;
+  runWithTsx(devScript, { ENVIRONMENT: 'development' });
+
+} else if (arg === 'build') {
+  // nuke build  →  run compiled dist via plain node
+  const isVercel = !!(
+    process.env.VERCEL ||
+    process.env.VERCEL_ENV ||
+    process.env.NOW_BUILDER
+  );
+
+  if (isVercel) {
+    runWithNode(path.join(distDir, 'build-vercel.js'));
+  } else {
+    runWithNode(path.join(distDir, 'build-node.js'));
+  }
+
+} else {
+  console.error(`\n  ✖  Unknown command: "${arg}"`);
+  console.error(`     Usage:  nuke [dev|build]\n`);
+  process.exit(1);
+}

package/dist/app.d.ts

@@ -0,0 +1,18 @@
+/**
+ * app.ts — NukeJS Dev Server Entry Point
+ *
+ * This is the runtime that powers `nuke dev`. It:
+ *   1. Loads your nuke.config.ts (or uses sensible defaults)
+ *   2. Discovers API route prefixes from your server directory
+ *   3. Starts an HTTP server that handles:
+ *        /__hmr_ping            — heartbeat for HMR reconnect polling
+ *        /__react.js            — bundled React + ReactDOM (resolved via importmap)
+ *        /__n.js                — NukeJS client runtime bundle
+ *        /__client-component/*  — on-demand "use client" component bundles
+ *        /api/**                — API route handlers from serverDir
+ *        /**                    — SSR pages from app/pages
+ *   4. Watches for file changes and broadcasts HMR events to connected browsers
+ *
+ * In production (ENVIRONMENT=production), HMR and all file watching are skipped.
+ */
+export {};