nukejs 0.0.14 → 0.0.16

package/README.md

@@ -17,6 +17,7 @@ npm create nuke@latest
 - [Pages & Routing](#pages--routing)
 - [Layouts](#layouts)
 - [Client Components](#client-components)
+- [State Management](#state-management)
 - [API Routes](#api-routes)
 - [Middleware](#middleware)
 - [Static Files](#static-files)
@@ -292,7 +293,142 @@ Children and other React elements can be passed as props — NukeJS serializes t
 
 ---
 
-## API Routes
+## State Management
+
+NukeJS ships a lightweight built-in store for sharing state across client components. Because each `"use client"` component is hydrated into its own independent React root, React Context cannot cross component boundaries — the store solves this.
+
+All store state lives in `window.__nukeStores`, so it is shared across every bundle on the page regardless of how many times a store module is evaluated.
+
+### createStore
+
+```ts
+import { createStore } from 'nukejs';
+
+const counterStore = createStore('counter', { count: 0 });
+```
+
+The first argument is a unique name used to key the store in the global registry. The second is the initial state. If two bundles call `createStore` with the same name, the first one wins and subsequent calls reuse the existing entry.
+
+### useStore
+
+```tsx
+"use client"
+import { useStore } from 'nukejs';
+import { counterStore } from '../stores/counter';
+
+export default function Counter() {
+  const { count } = useStore(counterStore);
+  return (
+    <div>
+      <p>{count}</p>
+      <button onClick={() => counterStore.setState(s => ({ count: s.count + 1 }))}>
+        Increment
+      </button>
+    </div>
+  );
+}
+```
+
+Pass an optional selector to avoid re-renders when unrelated parts of state change:
+
+```tsx
+// Only re-renders when `count` changes, not on any other state update
+const count = useStore(counterStore, s => s.count);
+```
+
+### Sharing state across components
+
+Stores shine when two completely separate client components need to stay in sync. Define the store in its own file (no `"use client"` needed) and import it from both:
+
+```ts
+// app/stores/cart.ts
+import { createStore } from 'nukejs';
+
+export type CartItem = { id: string; name: string; price: number };
+
+export const cartStore = createStore('cart', {
+  items: [] as CartItem[],
+  total: 0,
+});
+```
+
+```tsx
+// app/components/AddToCartButton.tsx
+"use client"
+import { cartStore, type CartItem } from '../stores/cart';
+
+export default function AddToCartButton({ item }: { item: CartItem }) {
+  return (
+    <button onClick={() =>
+      cartStore.setState(s => ({
+        items: [...s.items, item],
+        total: s.total + item.price,
+      }))
+    }>
+      Add to cart
+    </button>
+  );
+}
+```
+
+```tsx
+// app/components/CartIcon.tsx
+"use client"
+import { useStore } from 'nukejs';
+import { cartStore } from '../stores/cart';
+
+export default function CartIcon() {
+  const { items, total } = useStore(cartStore);
+  return (
+    <span>
+      🛒 {items.length} items — ${total.toFixed(2)}
+    </span>
+  );
+}
+```
+
+```tsx
+// app/pages/shop.tsx — server component, no JS cost
+import AddToCartButton from '../components/AddToCartButton';
+import CartIcon from '../components/CartIcon';
+
+export default function ShopPage() {
+  const item = { id: '1', name: 'Widget', price: 9.99 };
+  return (
+    <div>
+      <CartIcon />
+      <AddToCartButton item={item} />
+    </div>
+  );
+}
+```
+
+`CartIcon` updates instantly when the button is clicked — they are separate React roots with separate bundles, but they write and read through the same `'cart'` entry in `window.__nukeStores`.
+
+### setState
+
+Accepts a full replacement value or an updater function:
+
+```ts
+// Replace
+cartStore.setState({ items: [], total: 0 });
+
+// Updater — receives current state, returns next state
+cartStore.setState(s => ({ ...s, total: s.total + 5 }));
+```
+
+### API reference
+
+| | Description |
+|---|---|
+| `createStore(name, initialState)` | Creates or retrieves a named store |
+| `useStore(store)` | Subscribes to the full state |
+| `useStore(store, selector)` | Subscribes to a derived slice (re-renders only when slice changes) |
+| `store.getState()` | Returns the current state snapshot |
+| `store.setState(updater)` | Updates state and notifies all subscribers |
+| `store.subscribe(listener)` | Registers a listener; returns an unsubscribe function |
+
+
 
 Export named HTTP method handlers from `.ts` files in your `server/` directory.
 

package/dist/app.js

@@ -1,7 +1,7 @@
 import http from "http";
 import path from "path";
 import { existsSync, watch } from "fs";
-import { ansi, c, log, setDebugLevel, getDebugLevel } from "./logger.js";
+import { c, log, setDebugLevel, getDebugLevel } from "./logger.js";
 import { loadConfig } from "./config.js";
 import { discoverApiPrefixes, matchApiPrefix, createApiHandler } from "./http-server.js";
 import { loadMiddleware, runMiddleware } from "./middleware-loader.js";
@@ -9,6 +9,7 @@ import { serveReactBundle, serveNukeBundle, serveClientComponentBundle } from ".
 import { serverSideRender } from "./ssr.js";
 import { watchDir, broadcastRestart } from "./hmr.js";
 const isDev = process.env.ENVIRONMENT !== "production";
+const _startMs = Date.now();
 if (isDev) {
   const React = await import("react");
   global.React = React;
@@ -84,30 +85,28 @@ function tryListen(port) {
     server.listen(port, () => resolve(port));
   });
 }
-function printStartupBanner(port, isDev2) {
+function printStartupBanner(port, configuredPort, startMs) {
   const url = `http://localhost:${port}`;
   const level = getDebugLevel();
-  const debugStr = String(level);
-  const innerWidth = 42;
-  const line = "\u2500".repeat(innerWidth);
-  const pad = (text, width) => {
-    const visibleLen = text.replace(/\x1b\[[0-9;]*m/g, "").length;
-    return text + " ".repeat(Math.max(0, width - visibleLen));
+  const elapsed = Date.now() - startMs;
+  const keyW = 5;
+  const visible = (s) => s.replace(/\x1b\[[\d;]*m/g, "").length;
+  const row = (key, val) => {
+    const pad = " ".repeat(Math.max(0, keyW - visible(key)));
+    console.log(`  ${c("gray", key)}${pad}  ${val}`);
   };
-  const row = (content, w = 2) => `${ansi.gray}\u2502${ansi.reset} ${pad(content, innerWidth - w)} ${ansi.gray}\u2502${ansi.reset}`;
-  const label = (key, val) => row(`${c("gray", key)}  ${val}`);
   console.log("");
-  console.log(`${ansi.gray}\u250C${line}\u2510${ansi.reset}`);
-  console.log(row(`  ${c("red", "\u2622\uFE0F        nukejs ", true)}`, 1));
-  console.log(`${ansi.gray}\u251C${line}\u2524${ansi.reset}`);
-  console.log(label("  Local  ", c("cyan", url, true)));
-  console.log(`${ansi.gray}\u251C${line}\u2524${ansi.reset}`);
-  console.log(label("  Pages  ", c("white", path.relative(process.cwd(), PAGES_DIR))));
-  console.log(label("  Server ", c("white", path.relative(process.cwd(), SERVER_DIR))));
-  console.log(label("  Dev    ", isDev2 ? c("green", "yes") : c("gray", "no")));
-  console.log(label("  Debug  ", level === false ? c("gray", "off") : level === true ? c("green", "verbose") : c("yellow", debugStr)));
-  console.log(`${ansi.gray}\u2514${line}\u2518${ansi.reset}`);
+  console.log(`  ${c("orange", "NukeJS", true)}  ${c("gray", `ready in ${elapsed}ms`)}`);
+  console.log("");
+  row(
+    "Local",
+    port !== configuredPort ? `${c("cyan", url, true)}  ${c("yellow", `(${configuredPort} was in use)`)}` : c("cyan", url, true)
+  );
+  row(
+    "Debug",
+    level === false ? c("gray", "off") : level === true ? c("green", "verbose") : c("yellow", String(level))
+  );
   console.log("");
 }
 const actualPort = await tryListen(PORT);
-printStartupBanner(actualPort, isDev);
+printStartupBanner(actualPort, PORT, _startMs);

package/dist/build-common.js

@@ -618,7 +618,7 @@ export default async function handler(req: IncomingMessage, res: ServerResponse)
 
   <script id="__n_data" type="application/json">\${runtimeData}</script>
 
-  <script type="importmap">
+  \${hydrated.size > 0 ? \`<script type="importmap">
   {
     "imports": {
       "react":             "/__n.js",
@@ -633,7 +633,7 @@ export default async function handler(req: IncomingMessage, res: ServerResponse)
     const { initRuntime } = await import('nukejs');
     const data = JSON.parse(document.getElementById('__n_data').textContent);
     await initRuntime(data);
-  </script>
+  </script>\` : ''}
 \${bodyScriptsHtml}</body>
 </html>\`;
 
@@ -800,16 +800,19 @@ async function buildCombinedBundle(staticDir) {
     stdin: {
       contents: `
 import React, {
+  createElement, cloneElement, createRef, isValidElement, Children,
   useState, useEffect, useContext, useReducer, useCallback, useMemo,
   useRef, useImperativeHandle, useLayoutEffect, useDebugValue,
   useDeferredValue, useTransition, useId, useSyncExternalStore,
   useInsertionEffect, createContext, forwardRef, memo, lazy,
-  Suspense, Fragment, StrictMode, Component, PureComponent
+  Suspense, Fragment, StrictMode, Component, PureComponent,
+  createPortal
 } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { hydrateRoot, createRoot } from 'react-dom/client';
 export { initRuntime, setupLocationChangeMonitor } from "./${bundleFile}.js";
 export {
+  createElement, cloneElement, createRef, isValidElement, Children,
   useState, useEffect, useContext, useReducer, useCallback, useMemo,
   useRef, useImperativeHandle, useLayoutEffect, useDebugValue,
   useDeferredValue, useTransition, useId, useSyncExternalStore,

package/dist/builder.js

@@ -49,6 +49,7 @@ const PUBLIC_STEMS = /* @__PURE__ */ new Set([
   "request-store",
   "Link",
   "bundle",
+  "store",
   "utils",
   "logger"
 ]);

package/dist/bundler.js

@@ -37,16 +37,19 @@ async function serveReactBundle(res) {
       stdin: {
         contents: `
         import React, {
+          createElement, cloneElement, createRef, isValidElement, Children,
           useState, useEffect, useContext, useReducer, useCallback, useMemo,
           useRef, useImperativeHandle, useLayoutEffect, useDebugValue,
           useDeferredValue, useTransition, useId, useSyncExternalStore,
           useInsertionEffect, createContext, forwardRef, memo, lazy,
-          Suspense, Fragment, StrictMode, Component, PureComponent
+          Suspense, Fragment, StrictMode, Component, PureComponent,
+          createPortal
         } from 'react';
         import { jsx, jsxs } from 'react/jsx-runtime';
         import { hydrateRoot, createRoot } from 'react-dom/client';
 
         export {
+          createElement, cloneElement, createRef, isValidElement, Children,
           useState, useEffect, useContext, useReducer, useCallback, useMemo,
           useRef, useImperativeHandle, useLayoutEffect, useDebugValue,
           useDeferredValue, useTransition, useId, useSyncExternalStore,
@@ -75,7 +78,7 @@ async function serveReactBundle(res) {
   res.end(await reactBundlePromise);
 }
 async function serveNukeBundle(res) {
-  log.verbose("Bundling nuke runtime");
+  log.verbose("Bundling NukeJS runtime");
   if (!nukeBundlePromise) {
     const dir = path.dirname(fileURLToPath(import.meta.url));
     const entry = path.join(dir, `bundle.${dir.endsWith("dist") ? "js" : "ts"}`);

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { createStore, useStore } from './store';
+export type { Store } from './store';
 export { useHtml } from './use-html';
 export type { HtmlOptions } from './use-html';
 export type { TitleValue, HtmlAttrs, BodyAttrs, MetaTag, LinkTag, ScriptTag, StyleTag, } from './html-store';

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createStore, useStore } from "./store.js";
 import { useHtml } from "./use-html.js";
 import { default as default2 } from "./use-router.js";
 import { useRequest } from "./use-request.js";
@@ -10,6 +11,7 @@ export {
   default3 as Link,
   ansi,
   c,
+  createStore,
   escapeHtml,
   getDebugLevel,
   getRequestStore,
@@ -21,5 +23,6 @@ export {
   setupLocationChangeMonitor,
   useHtml,
   useRequest,
-  default2 as useRouter
+  default2 as useRouter,
+  useStore
 };

package/dist/logger.d.ts

@@ -26,6 +26,7 @@ export declare const ansi: {
     readonly cyan: "\u001B[36m";
     readonly white: "\u001B[37m";
     readonly gray: "\u001B[90m";
+    readonly orange: "\u001B[38;5;208m";
     readonly bgBlue: "\u001B[44m";
     readonly bgGreen: "\u001B[42m";
     readonly bgMagenta: "\u001B[45m";

package/dist/logger.js

@@ -11,6 +11,7 @@ const ansi = {
   cyan: "\x1B[36m",
   white: "\x1B[37m",
   gray: "\x1B[90m",
+  orange: "\x1B[38;5;208m",
   bgBlue: "\x1B[44m",
   bgGreen: "\x1B[42m",
   bgMagenta: "\x1B[45m"

package/dist/middleware-loader.js

@@ -11,7 +11,7 @@ async function loadMiddlewareFromPath(middlewarePath) {
   try {
     const mod = await import(pathToFileURL(middlewarePath).href);
     if (typeof mod.default === "function") {
-      middlewares.push(mod.default);
+      middlewares.push({ fn: mod.default, src: middlewarePath });
       log.info(`Middleware loaded from ${middlewarePath}`);
     } else {
       log.warn(`${middlewarePath} does not export a default function`);
@@ -34,10 +34,14 @@ async function loadMiddleware() {
 }
 async function runMiddleware(req, res) {
   if (middlewares.length === 0) return false;
-  for (const middleware of middlewares) {
-    await middleware(req, res);
+  for (const { fn, src } of middlewares) {
+    await fn(req, res);
     if (res.writableEnded || res.headersSent) {
-      log.verbose("Middleware handled request, skipping further processing");
+      const method = (req.method ?? "GET").toUpperCase();
+      const url = req.url ?? "/";
+      const status = res.statusCode;
+      const srcName = path.basename(src);
+      log.verbose(`middleware  ${method} ${url}  ${status}  (${srcName})`);
       return true;
     }
   }

package/dist/store.d.ts

@@ -0,0 +1,104 @@
+/**
+ * store.ts — NukeJS Client State Management
+ *
+ * Provides a lightweight, cross-boundary state system for "use client"
+ * components.  The core problem it solves: NukeJS hydrates every client
+ * component into its own independent React root (via hydrateRoot / createRoot),
+ * so React Context cannot carry state across component boundaries.  Each
+ * component's esbuild bundle is also a separate module instance, so a plain
+ * module-level variable would not be shared between bundles.
+ *
+ * Solution: all store state lives in `window.__nukeStores`, a Map that persists
+ * for the lifetime of the page regardless of how many times the store module
+ * is evaluated.  Every bundle that imports `createStore('counter', …)` gets
+ * a thin proxy object that reads from and writes to the same backing entry —
+ * state is automatically shared across roots and bundles.
+ *
+ * API:
+ *
+ *   const cartStore = createStore('cart', { items: [], total: 0 });
+ *
+ *   // Inside any "use client" component on the same page:
+ *   const items = useStore(cartStore, s => s.items);
+ *   cartStore.setState(s => ({ ...s, items: [...s.items, newItem] }));
+ *
+ * The store is safe to import in server components — it detects the absence of
+ * `window` and returns a lightweight no-op stub so SSR never throws.
+ */
+type Listener = () => void;
+type Unsubscribe = () => void;
+type Updater<T> = T | ((prev: T) => T);
+/**
+ * A NukeJS store handle.  Create it once at module scope; pass it into
+ * `useStore()` inside any client component to subscribe.
+ */
+export interface Store<T extends object> {
+    /** Returns the current state snapshot. */
+    getState(): T;
+    /**
+     * Updates the state and notifies every subscriber.
+     *
+     * Accepts a full replacement value or an updater function:
+     *   store.setState({ count: 0 })
+     *   store.setState(s => ({ ...s, count: s.count + 1 }))
+     */
+    setState(updater: Updater<T>): void;
+    /**
+     * Registers a change listener.  Returns an unsubscribe function.
+     * Compatible with `useSyncExternalStore`.
+     */
+    subscribe(listener: Listener): Unsubscribe;
+    /** The name this store is registered under in the global registry. */
+    readonly name: string;
+    /**
+     * The value passed to `createStore` as its second argument.
+     * Used internally as the server snapshot so `useSyncExternalStore` always
+     * reconciles against a value that matches the server-rendered HTML —
+     * the server never has mutations, so initial state is always what it renders.
+     */
+    readonly initialState: T;
+}
+interface StoreEntry<T> {
+    state: T;
+    listeners: Set<Listener>;
+}
+declare global {
+    interface Window {
+        __nukeStores?: Map<string, StoreEntry<any>>;
+    }
+}
+/**
+ * Creates (or retrieves) a named store backed by the page-global registry.
+ *
+ * If a store with the given `name` already exists in the registry (e.g.
+ * because another bundle called `createStore` first), the existing entry is
+ * reused and `initialState` is ignored.  This means the first bundle to run
+ * wins the initial value — define your stores in a single shared file, or
+ * treat `initialState` as a consistent default across all bundles.
+ *
+ * @param name          A unique string key for this store.
+ * @param initialState  Default state used when the store is first created.
+ */
+export declare function createStore<T extends object>(name: string, initialState: T): Store<T>;
+/**
+ * React hook that subscribes a component to a store.
+ *
+ * An optional `selector` lets you derive a slice of state.  The component
+ * only re-renders when the selected value changes (by reference equality),
+ * not on every store mutation.
+ *
+ * Works across independent React roots — any component on the page that calls
+ * `useStore` with the same store will re-render when that store changes,
+ * regardless of which component boundary each lives in.
+ *
+ * @example
+ * // Full state
+ * const state = useStore(cartStore);
+ *
+ * @example
+ * // Selected slice — re-renders only when `items` changes
+ * const items = useStore(cartStore, s => s.items);
+ */
+export declare function useStore<T extends object>(store: Store<T>): T;
+export declare function useStore<T extends object, U>(store: Store<T>, selector: (state: T) => U): U;
+export {};

package/dist/store.js

@@ -0,0 +1,45 @@
+import { useSyncExternalStore } from "react";
+function getRegistry() {
+  if (typeof window === "undefined") {
+    return /* @__PURE__ */ new Map();
+  }
+  if (!window.__nukeStores) {
+    window.__nukeStores = /* @__PURE__ */ new Map();
+  }
+  return window.__nukeStores;
+}
+function createStore(name, initialState) {
+  const registry = getRegistry();
+  if (!registry.has(name)) {
+    registry.set(name, {
+      state: initialState,
+      listeners: /* @__PURE__ */ new Set()
+    });
+  }
+  const entry = registry.get(name);
+  const subscribe = (listener) => {
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+    };
+  };
+  const getState = () => entry.state;
+  const setState = (updater) => {
+    entry.state = typeof updater === "function" ? updater(entry.state) : updater;
+    for (const l of Array.from(entry.listeners)) l();
+  };
+  return { name, initialState, getState, setState, subscribe };
+}
+function useStore(store, selector) {
+  const getSnapshot = selector ? () => selector(store.getState()) : () => store.getState();
+  const getServerSnapshot = selector ? () => selector(store.initialState) : () => store.initialState;
+  return useSyncExternalStore(
+    store.subscribe,
+    getSnapshot,
+    getServerSnapshot
+  );
+}
+export {
+  createStore,
+  useStore
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nukejs",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "A minimal, opinionated full-stack React framework on Node.js that server-renders everything and hydrates only interactive parts.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",