npm - nukejs - Versions diffs - 0.0.5 → 0.0.7 - Mend

nukejs 0.0.5 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/README.md +96 -8
package/dist/Link.js +16 -0
package/dist/Link.js.map +7 -0
package/dist/build-common.d.ts +57 -80
package/dist/build-common.js +156 -168
package/dist/build-common.js.map +2 -2
package/dist/build-node.d.ts +14 -0
package/dist/build-node.js +50 -51
package/dist/build-node.js.map +2 -2
package/dist/build-vercel.d.ts +18 -0
package/dist/build-vercel.js +76 -63
package/dist/build-vercel.js.map +2 -2
package/dist/builder.d.ts +10 -0
package/dist/builder.js +31 -62
package/dist/builder.js.map +3 -3
package/dist/bundle.js +69 -6
package/dist/bundle.js.map +2 -2
package/dist/component-analyzer.d.ts +13 -10
package/dist/component-analyzer.js +26 -17
package/dist/component-analyzer.js.map +2 -2
package/dist/hmr-bundle.js +17 -4
package/dist/hmr-bundle.js.map +2 -2
package/dist/html-store.d.ts +7 -0
package/dist/html-store.js.map +2 -2
package/dist/index.d.ts +2 -2
package/dist/index.js +2 -2
package/dist/index.js.map +1 -1
package/dist/renderer.js +2 -7
package/dist/renderer.js.map +2 -2
package/dist/router.js +16 -4
package/dist/router.js.map +2 -2
package/dist/ssr.js +21 -4
package/dist/ssr.js.map +2 -2
package/dist/use-html.js +5 -1
package/dist/use-html.js.map +2 -2
package/dist/use-router.js +28 -0
package/dist/use-router.js.map +7 -0
package/package.json +1 -1
package/dist/as-is/Link.tsx +0 -20
package/dist/as-is/useRouter.ts +0 -33
/package/dist/{as-is/Link.d.ts → Link.d.ts} +0 -0
/package/dist/{as-is/useRouter.d.ts → use-router.d.ts} +0 -0

package/README.md CHANGED Viewed

@@ -1,9 +1,11 @@
-# ☢️ NukeJS
+[![NukeJS Banner](.github/banner.png)](https://nukejs.com)
+# NukeJS
 A **minimal**, opinionated full-stack React framework on Node.js that server-renders everything and hydrates only interactive parts.
 ```
-npm create nuke
+npm create nuke@latest
 ```
 ## Table of Contents
@@ -19,6 +21,7 @@ npm create nuke
 - [Static Files](#static-files)
 - [useHtml() — Head Management](#usehtml--head-management)
 - [Configuration](#configuration)
+- [Link Component & Navigation](#link-component--navigation)
 - [Building & Deploying](#building--deploying)
 ## Overview
@@ -129,8 +132,9 @@ Each `.tsx` file in `app/pages/` maps to a URL route:
 | `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) |
+| `docs/[...path].tsx` | `/docs/*` (catch-all, required) |
+| `users/[[id]].tsx` | `/users` or `/users/42` (optional single segment) |
+| `files/[[...path]].tsx` | `/files` or `/files/*` (optional catch-all) |
 ### Page component
@@ -151,6 +155,28 @@ export default async function BlogPost({ slug }: { slug: string }) {
 Route params are passed as props to the component.
+### Query string params
+Query string parameters are automatically merged into the page component's props alongside route params. If a query param shares a name with a route param, the route param takes precedence.
+```tsx
+// app/pages/search.tsx
+// URL: /search?q=nuke&page=2
+export default function Search({ q, page }: { q: string; page: string }) {
+  return <h1>Results for "{q}" — page {page}</h1>;
+}
+```
+```tsx
+// app/pages/blog/[slug].tsx
+// URL: /blog/hello-world?preview=true
+export default function BlogPost({ slug, preview }: { slug: string; preview?: string }) {
+  return <article data-preview={preview}>{slug}</article>;
+}
+```
+A query param that appears multiple times (e.g. `?tag=a&tag=b`) is passed as a `string[]`.
 ### Catch-all routes
 ```tsx
@@ -168,9 +194,12 @@ 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          → users/[[id]].tsx    (optional single, matches with no id)
 /users/a/b/c    → users/[...rest].tsx (catch-all)
 ```
+Specificity order, highest to lowest: static → `[param]` → `[[param]]` → `[...catchAll]` → `[[...optionalCatchAll]]`.
 ---
 ## Layouts
@@ -383,13 +412,13 @@ export default function Layout({ children }: { children: React.ReactNode }) {
 | `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`.
+On Vercel, public files receive the same zero-latency CDN treatment as `__n.js`.
 ---
 ## useHtml() — Head Management
-The `useHtml()` hook works in both server components and client components to control the document head.
+The `useHtml()` hook works in both server components and client components to control the document `<head>`, `<html>` attributes, `<body>` attributes, and scripts injected at the end of `<body>`.
 ```tsx
 import { useHtml } from 'nukejs';
@@ -428,6 +457,65 @@ Result: "Home | Site"
 The page title always serves as the base value; layout functions wrap it outward.
+### Script injection & position
+The `script` option accepts an array of script tags. Each entry supports the standard attributes (`src`, `type`, `async`, `defer`, `content` for inline scripts, etc.) plus a `position` field:
+| `position` | Where it's injected |
+|---|---|
+| `'head'` (default) | Inside `<head>`, in the managed `<!--n-head-->` block |
+| `'body'` | End of `<body>`, just before `</body>`, in the `<!--n-body-scripts-->` block |
+**Use `position: 'body'`** for third-party analytics and tracking scripts (Google Analytics, Hotjar, Intercom, etc.) that should load after page content is in the DOM and must not block rendering.
+```tsx
+// app/pages/layout.tsx — Google Analytics on every page
+import { useHtml } from 'nukejs';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  useHtml({
+    script: [
+      // Load the gtag library — async so it doesn't block rendering
+      {
+        src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX',
+        async: true,
+        position: 'body',
+      },
+      // Inline initialisation — must follow the loader above
+      {
+        content: `
+          window.dataLayer = window.dataLayer || [];
+          function gtag(){dataLayer.push(arguments);}
+          gtag('js', new Date());
+          gtag('config', 'G-XXXXXXXXXX');
+        `,
+        position: 'body',
+      },
+    ],
+  });
+  return <>{children}</>;
+}
+```
+**Use `position: 'head'` (the default)** for scripts that must run before first paint, such as theme detection to avoid flash-of-unstyled-content:
+```tsx
+useHtml({
+  script: [
+    {
+      content: `
+        const theme = localStorage.getItem('theme') ?? 'light';
+        document.documentElement.classList.add(theme);
+      `,
+      // position defaults to 'head' — runs before the page renders
+    },
+  ],
+});
+```
+Both head and body scripts are re-executed on every HMR update and SPA navigation so they always reflect the current page state.
 ---
 ## Configuration
@@ -506,8 +594,7 @@ dist/
 ├── api/            # Bundled API route handlers (.mjs)
 ├── pages/          # Bundled page handlers (.mjs)
 ├── static/
-│   ├── __react.js          # Bundled React runtime
-│   ├── __n.js              # NukeJS client runtime
+│   ├── __n.js              # NukeJS client runtime (React + NukeJS bundled together)
 │   ├── __client-component/ # Bundled "use client" component files
 │   └── <app/public files>  # Copied from app/public/ at build time
 ├── manifest.json   # Route dispatch table
@@ -515,6 +602,7 @@ dist/
 ```
 ### Vercel
 Just import the code from GitHub.
 ### Environment variables

package/dist/Link.js ADDED Viewed

@@ -0,0 +1,16 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import useRouter from "./use-router.js";
+const Link = ({ href, children, className }) => {
+  const r = useRouter();
+  const handleClick = (e) => {
+    e.preventDefault();
+    r.push(href);
+  };
+  return /* @__PURE__ */ jsx("a", { href, onClick: handleClick, className, children });
+};
+var Link_default = Link;
+export {
+  Link_default as default
+};
+//# sourceMappingURL=Link.js.map

package/dist/Link.js.map ADDED Viewed

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/Link.tsx"],
+  "sourcesContent": ["\"use client\"\r\nimport useRouter from \"./use-router\"\r\n\r\nconst Link = ({ href, children, className }: {\r\n    href: string;\r\n    children: React.ReactNode;\r\n    className?: string;\r\n}) => {\r\n    const r = useRouter()\r\n    const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {\r\n        e.preventDefault();\r\n        r.push(href);\r\n    }\r\n    return (\r\n        <a href={href} onClick={handleClick} className={className} >\r\n            {children}\r\n        </a >\r\n    );\r\n};\r\n\r\nexport default Link;\r\n"],
+  "mappings": ";AAcQ;AAbR,OAAO,eAAe;AAEtB,MAAM,OAAO,CAAC,EAAE,MAAM,UAAU,UAAU,MAIpC;AACF,QAAM,IAAI,UAAU;AACpB,QAAM,cAAc,CAAC,MAA2C;AAC5D,MAAE,eAAe;AACjB,MAAE,KAAK,IAAI;AAAA,EACf;AACA,SACI,oBAAC,OAAE,MAAY,SAAS,aAAa,WAChC,UACL;AAER;AAEA,IAAO,eAAQ;",
+  "names": []
+}

package/dist/build-common.d.ts CHANGED Viewed

@@ -1,41 +1,59 @@
 /**
- * build-common.ts
+ * build-common.ts — Shared Build Logic
  *
- * Shared build logic used by both build-vercel.ts and build-node.ts.
+ * Used by both build-node.ts and build-vercel.ts.
  *
  * Exports:
- *   — utility helpers   : walkFiles, analyzeFile, isServerComponent,
- *                         findPageLayouts, extractDefaultExportName
- *   — collection        : collectServerPages, collectGlobalClientRegistry
- *   — template codegen  : makeApiAdapterSource, makePageAdapterSource
- *   — bundle operations : bundleApiHandler, bundlePageHandler,
- *                         bundleClientComponents, buildCombinedBundle
+ *   — types            : AnalyzedRoute, ServerPage, BuiltPage,
+ *                        PageAdapterOptions, PageBundleOptions
+ *   — utility helpers  : walkFiles, analyzeFile, isServerComponent,
+ *                        findPageLayouts, extractDefaultExportName
+ *   — collection       : collectServerPages, collectGlobalClientRegistry,
+ *                        buildPerPageRegistry
+ *   — template codegen : makeApiAdapterSource, makePageAdapterSource
+ *   — bundle ops       : bundleApiHandler, bundlePageHandler,
+ *                        bundleClientComponents, buildPages,
+ *                        buildCombinedBundle, copyPublicFiles
  */
 export interface AnalyzedRoute {
+    /** Regex string matching the URL path, e.g. '^/users/([^/]+)$' */
     srcRegex: string;
+    /** Names of captured groups in srcRegex order */
     paramNames: string[];
-    /** Path used as function namespace, e.g. '/api/users' or '/page/about'. */
+    /**
+     * Subset of paramNames that are catch-all ([...slug] or [[...path]]).
+     * Their runtime values are string[] not string.
+     */
+    catchAllNames: string[];
+    /** Function namespace path, e.g. '/api/users' or '/page/about' */
     funcPath: string;
     specificity: number;
 }
 export interface ServerPage extends AnalyzedRoute {
     absPath: string;
 }
-/** A server page together with its fully bundled ESM text, ready to emit. */
 export interface BuiltPage extends ServerPage {
     bundleText: string;
 }
 export declare function walkFiles(dir: string, base?: string): string[];
 /**
  * Parses dynamic-route segments from a relative file path and returns a regex,
- * captured param names, a function path, and a specificity score.
+ * captured param names, catch-all param names, a function path, and a
+ * specificity score.
+ *
+ * Supported patterns per segment:
+ *   [[...name]]  optional catch-all  → regex (.*)      → string[]
+ *   [...name]    required catch-all  → regex (.+)      → string[]
+ *   [[name]]     optional single     → regex ([^/]*)?  → string
+ *   [name]       required single     → regex ([^/]+)   → string
+ *   literal      static              → escaped literal
  *
  * @param relPath  Relative path from the dir root (e.g. 'users/[id].tsx').
  * @param prefix   Namespace for funcPath ('api' | 'page').
  */
 export declare function analyzeFile(relPath: string, prefix?: string): AnalyzedRoute;
 /**
- * Returns true when a file does NOT begin with a "use client" directive —
+ * Returns true when a file does NOT begin with a "use client" directive,
  * i.e. it is a server component.
  */
 export declare function isServerComponent(filePath: string): boolean;
@@ -47,26 +65,29 @@ export declare function findPageLayouts(routeFilePath: string, pagesDir: string)
 /**
  * Extracts the identifier used as the default export from a component file.
  * Returns null when no default export is found.
+ *
+ * Handles three formats so that components compiled by esbuild are recognised
+ * alongside hand-written source files:
+ *   1. Source:   `export default function Foo` / `export default Foo`
+ *   2. esbuild:  `var Foo_default = Foo`  (compiled arrow-function component)
+ *   3. Re-export: `export { Foo as default }`
  */
 export declare function extractDefaultExportName(filePath: string): string | null;
 /**
- * Returns all server-component pages inside `pagesDir`, sorted by specificity
- * (most-specific first so more-precise routes shadow catch-alls in routers).
+ * Returns all server-component pages inside `pagesDir`, sorted most-specific
+ * first so precise routes shadow catch-alls in routers.
  * layout.tsx files and "use client" files are excluded.
  */
 export declare function collectServerPages(pagesDir: string): ServerPage[];
 /**
  * Walks every server page and its layout chain to collect all client component
- * IDs reachable anywhere in the app.  Deduplication is automatic because the
- * Map key is the stable content-hash ID produced by component-analyzer.ts.
+ * IDs reachable anywhere in the app.
  */
 export declare function collectGlobalClientRegistry(serverPages: ServerPage[], pagesDir: string): Map<string, string>;
 /**
- * Builds the per-page client component registry (page + its layout chain) and
- * returns both the id→path map and the name→id map needed by bundlePageHandler.
- *
- * Extracted here to eliminate the identical loop duplicated across
- * build-node.ts and build-vercel.ts.
+ * Builds the per-page client component registry (page + its layout chain)
+ * and returns both the id→path map and the name→id map needed by
+ * bundlePageHandler.
  */
 export declare function buildPerPageRegistry(absPath: string, layoutPaths: string[], pagesDir: string): {
     registry: Map<string, string>;
@@ -79,19 +100,11 @@ export declare function buildPerPageRegistry(absPath: string, layoutPaths: strin
  *             and collects pre-rendered HTML for each.
  *   Pass 2 — bundles every server-component page into a self-contained ESM
  *             handler and returns the results as `BuiltPage[]`.
- *
- * Callers (build-node, build-vercel) only need to write the bundled text to
- * their respective output destinations — the format-specific logic stays local.
- *
- * Returns an empty array when there are no server pages.
  */
 export declare function buildPages(pagesDir: string, staticDir: string): Promise<BuiltPage[]>;
 /**
  * Returns the TypeScript source for a thin HTTP adapter that wraps an API
  * route module and exposes a single `handler(req, res)` default export.
- *
- * @param handlerFilename  Basename of the handler file relative to the adapter
- *                         (e.g. 'users.ts').  Must be in the same directory.
  */
 export declare function makeApiAdapterSource(handlerFilename: string): string;
 export interface PageAdapterOptions {
@@ -107,27 +120,24 @@ export interface PageAdapterOptions {
     layoutArrayItems: string;
     /** Pre-rendered HTML per client component ID, computed at build time */
     prerenderedHtml: Record<string, string>;
+    /** Catch-all param names whose runtime values are string[] not string */
+    catchAllNames: string[];
 }
 /**
  * Returns the TypeScript source for a fully self-contained page handler.
  *
  * The adapter:
  *   • Inlines the html-store so useHtml() works without external deps.
- *   • Contains an async recursive renderer that handles server + client
- *     components without react-dom/server.
+ *   • Contains an async recursive renderer for server + client components.
  *   • Client components are identified via the pre-computed CLIENT_COMPONENTS
- *     map (no fs.readFileSync at runtime).
- *   • Emits the same full HTML document structure as ssr.ts including the
- *     __n_data blob, importmap, and initRuntime bootstrap.
+ *     map — no fs.readFileSync at runtime.
+ *   • Emits the full HTML document including the __n_data blob and bootstrap.
  */
 export declare function makePageAdapterSource(opts: PageAdapterOptions): string;
 /**
  * Bundles an API route handler into a single self-contained ESM string.
- *
- * Writes a temporary adapter next to `absPath`, bundles them together with
- * esbuild (node_modules kept external), then removes the temp file.
- *
- * @returns The bundled ESM text ready to write to disk.
+ * node_modules are kept external — they exist at runtime on both Node and
+ * Vercel (Vercel bundles them separately via the pages dispatcher).
  */
 export declare function bundleApiHandler(absPath: string): Promise<string>;
 export interface PageBundleOptions {
@@ -137,59 +147,26 @@ export interface PageBundleOptions {
     allClientIds: string[];
     layoutPaths: string[];
     prerenderedHtml: Record<string, string>;
+    catchAllNames: string[];
 }
 /**
  * Bundles a server-component page into a single self-contained ESM string.
- *
- * Writes a temporary adapter next to `absPath` (so relative imports inside
- * the component resolve from the correct base directory), bundles it with
- * esbuild (React and all npm deps inlined, only Node built-ins stay external),
- * then removes the temp file.
- *
- * @returns The bundled ESM text ready to write to disk.
+ * All npm packages are kept external — the Node production server has
+ * node_modules available at runtime.
  */
 export declare function bundlePageHandler(opts: PageBundleOptions): Promise<string>;
 /**
  * Bundles every client component in `globalRegistry` to
- * `<staticDir>/__client-component/<id>.js`.
- *
- * Mirrors bundleClientComponent() in bundler.ts:
- *   • browser ESM, JSX automatic
- *   • react / react-dom/client / react/jsx-runtime kept external so the
- *     importmap can resolve them to the already-loaded /__react.js bundle.
+ * `<staticDir>/__client-component/<id>.js` and pre-renders each to HTML.
  */
 export declare function bundleClientComponents(globalRegistry: Map<string, string>, pagesDir: string, staticDir: string): Promise<Map<string, string>>;
 /**
- * Builds a single combined browser bundle to `<staticDir>/__n.js`.
- *
- * Inlines the full React + ReactDOM runtime together with the NukeJS client
- * runtime (bundle.ts) so the browser only needs one file instead of two.
- * The importmap in every page points 'react', 'react-dom/client',
- * 'react/jsx-runtime', and 'nukejs' all to /__n.js, so dynamic imports
- * inside the runtime (e.g. `await import('react')`) hit the module cache
- * and return the same singleton that was already loaded.
- *
- * Dev mode (bundler.ts) keeps separate /__react.js and /__n.js files for
- * easier debugging — this function is production-only.
+ * Builds the combined browser bundle (__n.js) that contains the full React
+ * runtime + NukeJS client runtime in a single file.
  */
 export declare function buildCombinedBundle(staticDir: string): Promise<void>;
 /**
- * Recursively copies every file from `app/public/` into `destDir`,
- * preserving the directory structure.
- *
- * Called by both build-vercel.ts (dest = .vercel/output/static/) and
- * build-node.ts (dest = dist/static/) so that:
- *
- *   app/public/favicon.ico        → <destDir>/favicon.ico
- *   app/public/images/logo.png    → <destDir>/images/logo.png
- *
- * On Vercel, the Build Output API v3 serves everything in .vercel/output/static/
- * directly — no route entry needed, same as __react.js and __n.js.
- *
- * On Node, the serverEntry template serves files from dist/static/ with the
- * same MIME-type logic as the dev middleware.
- *
- * Skips silently when the public directory does not exist so projects without
- * one don't need any special configuration.
+ * Recursively copies every file from `publicDir` into `destDir`, preserving
+ * the directory structure.  Skips silently when `publicDir` does not exist.
  */
 export declare function copyPublicFiles(publicDir: string, destDir: string): void;