nukejs 0.0.27 → 0.0.29

package/README.md

@@ -17,6 +17,7 @@ npm create nuke@latest
 - [Pages & Routing](#pages--routing)
 - [Layouts](#layouts)
 - [Client Components](#client-components)
+- [Web Workers](#web-workers)
 - [State Management](#state-management)
 - [API Routes](#api-routes)
 - [Middleware](#middleware)
@@ -25,6 +26,7 @@ npm create nuke@latest
 - [Configuration](#configuration)
 - [Link Component & Navigation](#link-component--navigation)
 - [useRequest() — URL Params, Query & Headers](#userequest--url-params-query--headers)
+- [cache() — Request-Scoped Data Caching](#cache--request-scoped-data-caching)
 - [Error Pages](#error-pages)
 - [Building & Deploying](#building--deploying)
 
@@ -293,6 +295,65 @@ Children and other React elements can be passed as props — NukeJS serializes t
 
 ---
 
+## Web Workers
+
+`"use client"` components can create Web Workers using the standard modern bundler pattern — no manual copying of worker files into `app/public/`, and no extra config:
+
+```ts
+"use client";
+
+function makeParserWorker() {
+  return new Worker(new URL("./parser.worker.ts", import.meta.url), {
+    type: "module",
+  });
+}
+```
+
+Any `new URL("./relative/path", import.meta.url)` reachable from a client component is discovered automatically while NukeJS bundles your app. The referenced file is bundled with esbuild as its own entry point, written out with a content hash in its filename, and the `new URL(...)` call is rewritten in place to point at the emitted file — in both `nuke dev` and `nuke build`, under the same `/__worker/<name>-<hash>.js` URL, so app code never has to branch on mode.
+
+### Workers from installed packages
+
+This also works when the worker lives inside a package you installed, either because the package references its own co-located worker internally:
+
+```ts
+// resolved correctly even though voiceClient.js ships inside node_modules
+new URL("./workers/stt-worker.js", import.meta.url)
+```
+
+or because your own code points at a worker a package exports by subpath:
+
+```ts
+new Worker(
+  new URL("monaco-editor/esm/vs/language/json/json.worker.js", import.meta.url),
+  { type: "module" }
+)
+```
+
+Bare specifiers are resolved through Node's own module resolution (honoring that package's `exports`/`main`), so the correct installed copy is found the same way a real `import` of that specifier would find it.
+
+### Overriding the URL
+
+Nothing here gets in the way of supplying your own worker URL at runtime — that's just a plain string, which is never something this rewrite touches:
+
+```ts
+function makeParserWorker(options: { workerUrls?: { parser?: string } } = {}) {
+  if (options.workerUrls?.parser) {
+    return new Worker(options.workerUrls.parser, { type: "module" });
+  }
+  return new Worker(new URL("./parser.worker.ts", import.meta.url), {
+    type: "module",
+  });
+}
+```
+
+If `options.workerUrls.parser` is set, it's always used. Otherwise the bundled worker is resolved automatically.
+
+### What's still out of reach
+
+Only string literals are resolved — a dynamic path (`new URL(someVariable, import.meta.url)`) can't be, since there's nothing to inspect until the code actually runs. And a worker a package never spells out as a specifier anywhere — no relative path, no subpath export, located via some entirely runtime-only scheme — can't be resolved by any static, build-time plugin, for this or any other bundler.
+
+---
+
 ## 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.
@@ -1104,6 +1165,73 @@ Changing `?lang=fr` in the URL re-renders client components automatically.
 
 ---
 
+## cache() — Request-Scoped Data Caching
+
+Server components render independently, so if two components in the same page tree both need the same data, NukeJS has no way to know they're asking for the same thing — each one triggers its own database call, fetch, or computation, even though they're part of the same request:
+
+```tsx
+// app/components/Nav.tsx
+export default async function Nav() {
+  const user = await db.getUser(useRequest().params.id); // DB call #1
+  return <nav>{user.name}</nav>;
+}
+
+// app/pages/dashboard.tsx
+export default async function Dashboard() {
+  const user = await db.getUser(useRequest().params.id); // DB call #2 — same data
+  return <main>{user.email}</main>;
+}
+```
+
+`cache()` wraps an async function so repeated calls with the same arguments, **within the same request**, share a single call:
+
+```ts
+// lib/data.ts
+import { cache } from 'nukejs';
+
+export const getUser = cache(async (id: string) => {
+  return db.getUser(id); // only runs once per request, however many
+                          // components call getUser(id) with that id
+});
+```
+
+```tsx
+// app/components/Nav.tsx
+import { getUser } from '../../lib/data';
+
+export default async function Nav() {
+  const user = await getUser(useRequest().params.id as string);
+  return <nav>{user.name}</nav>;
+}
+
+// app/pages/dashboard.tsx
+import { getUser } from '../../lib/data';
+
+export default async function Dashboard() {
+  const user = await getUser(useRequest().params.id as string); // same call → no extra DB hit
+  return <main>{user.email}</main>;
+}
+```
+
+Whichever component calls `getUser('42')` first triggers the real call; every other call with `'42'` in that same request — even ones that fire concurrently, before the first has resolved — awaits that same in-flight promise instead of starting a new one.
+
+### Why not just use React's `cache()`?
+
+React ships its own `cache()`, but it relies on the React Server Components renderer to signal "this is a new request, reset the memoization table." NukeJS doesn't run the RSC protocol — it renders each request to a single HTML string (see [Pages & Routing](#pages--routing)) — so nothing would ever tell React's `cache()` to reset, risking one request's cached data leaking into another's response. NukeJS's `cache()` has the same signature and mental model as React's, but is tied to NukeJS's own per-request lifecycle instead, so it resets correctly on every request.
+
+### Scope & behaviour
+
+- **One request, one cache.** The cache is created fresh before rendering starts and discarded once the response is sent. There's no cross-request caching and nothing to invalidate — the next request simply starts with an empty cache.
+- **Keyed by function + arguments.** Two different `cache()`-wrapped functions never share entries, even if called with identical arguments. Arguments are compared by value (via JSON serialization), so `getUser('42')` and `getUser('42')` hit the same entry, but `getUser('42')` and `getUser('43')` don't.
+- **Concurrent calls are deduped too.** If two components call the same cached function before the first call has settled, both await the same pending promise — only one underlying call is made.
+- **Failed calls aren't stuck.** If a cached call rejects, that entry is removed immediately, so a later call with the same arguments in the same request retries instead of replaying the same error.
+- **Non-serializable arguments skip caching.** Arguments that can't be safely compared by value (functions, Symbols, cyclic objects) just call straight through, unmemoized, rather than being cached under an incorrect key.
+- **Safe to call anywhere.** Outside of an active request — a script, a test, client-side code — a `cache()`-wrapped function simply calls straight through with no memoization. It's always safe to import and call.
+
+`cache()` is a pure optimization: removing it (or calling the wrapped function directly) never changes what your app returns, only how many times the underlying work runs.
+
+---
+
 ## Error Pages
 
 NukeJS supports custom error pages for **404 Not Found** and **500 Internal Server Error**. Place them directly in `app/pages/` — they are standard server components and support everything regular pages do: layouts, `useHtml()`, client components, and HMR in dev.
@@ -1268,6 +1396,7 @@ dist/
 ├── static/
 │   ├── __n.js              # NukeJS client runtime (React + NukeJS bundled together)
 │   ├── __client-component/ # Bundled "use client" component files
+│   ├── __worker/            # Auto-discovered Web Worker bundles (see Web Workers)
 │   └── <app/public files>  # Copied from app/public/ at build time
 ├── manifest.json   # Route dispatch table
 └── index.mjs       # HTTP server entry point
@@ -1289,6 +1418,7 @@ The build output goes to `.cloudflare/output/`:
 └── static/
     ├── __n.js                  # NukeJS client runtime
     ├── __client-component/     # Bundled "use client" component files
+    ├── __worker/                # Auto-discovered Web Worker bundles (see Web Workers) — unrelated to _worker.mjs above, which is Cloudflare's own deployment unit
     └── <app/public files>      # Copied from app/public/ at build time
 ```
 

package/dist/app.js

@@ -5,7 +5,7 @@ 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";
-import { serveReactBundle, serveNukeBundle, serveClientComponentBundle } from "./bundler.js";
+import { serveReactBundle, serveNukeBundle, serveClientComponentBundle, serveWorkerAsset } from "./bundler.js";
 import { serverSideRender } from "./ssr.js";
 import { watchDir, broadcastRestart } from "./hmr.js";
 const isDev = process.env.ENVIRONMENT !== "production";
@@ -67,6 +67,8 @@ const server = http.createServer(async (req, res) => {
         url.slice(20).split("?")[0].replace(".js", ""),
         res
       );
+    if (url.startsWith("/__worker/"))
+      return await serveWorkerAsset(url.slice("/__worker/".length).split("?")[0], res);
     if (matchApiPrefix(url, apiPrefixes))
       return await handleApiRoute(url, req, res);
     return await serverSideRender(url, res, PAGES_DIR, isDev, req);

package/dist/build-common.js

@@ -4,6 +4,7 @@ import { randomBytes } from "node:crypto";
 import { fileURLToPath, pathToFileURL } from "url";
 import { build } from "esbuild";
 import { findClientComponentsInTree } from "./component-analyzer.js";
+import { WorkerAssetRegistry, createWorkerUrlPlugin } from "./worker-assets.js";
 const NODE_BUILTINS = [
   "node:*",
   "http",
@@ -387,6 +388,46 @@ async function runWithRequestStore<T>(ctx: any, fn: () => Promise<T>): Promise<T
   try { return await fn(); } finally { __setReq(null); }
 }
 
+// \u2500\u2500\u2500 cache-store (inlined) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// See src/cache-store.ts for the full explanation. Request-scoped memoisation
+// for async data loaders, keyed on the wrapped function + its (serialisable)
+// arguments. Reset per request exactly like the request/html stores above.
+const __CACHE_KEY__ = Symbol.for('__nukejs_cache_store__');
+const __getCache = (): { entries: Map<string, Promise<unknown>> } | null =>
+  (globalThis as any)[__CACHE_KEY__] ?? null;
+const __setCache = (v: { entries: Map<string, Promise<unknown>> } | null): void => {
+  (globalThis as any)[__CACHE_KEY__] = v;
+};
+async function runWithCacheStore<T>(fn: () => Promise<T>): Promise<T> {
+  __setCache({ entries: new Map() });
+  try { return await fn(); } finally { __setCache(null); }
+}
+let __cacheIdCounter = 0;
+function __serialiseArgs(args: unknown[]): string | null {
+  try {
+    return JSON.stringify(args, (_k, v) => {
+      if (typeof v === 'function' || typeof v === 'symbol') throw new Error('non-serialisable');
+      return v;
+    });
+  } catch { return null; }
+}
+function cache<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>): (...args: Args) => Promise<R> {
+  const id = \`c\${++__cacheIdCounter}\`;
+  return function cached(...args: Args): Promise<R> {
+    const store = __getCache();
+    if (!store) return fn(...args);
+    const argsKey = __serialiseArgs(args);
+    if (argsKey === null) return fn(...args);
+    const key = \`\${id}:\${argsKey}\`;
+    const existing = store.entries.get(key);
+    if (existing) return existing as Promise<R>;
+    const result = fn(...args);
+    store.entries.set(key, result);
+    result.catch(() => { store.entries.delete(key); });
+    return result;
+  };
+}
+
 // \u2500\u2500\u2500 HTML helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
 function escapeHtml(s: string): string {
   return String(s)
@@ -688,7 +729,7 @@ export default async function handler(req: IncomingMessage, res: ServerResponse)
     let appHtml = '';
     const store = await runWithRequestStore(
       { url, pathname, params, query, headers: normHeaders },
-      () => runWithHtmlStore(async () => { appHtml = await renderNode(wrapped, hydrated); }),
+      () => runWithCacheStore(() => runWithHtmlStore(async () => { appHtml = await renderNode(wrapped, hydrated); })),
     );
 
     const pageTitle = resolveTitle(store.titleOps, 'NukeJS');
@@ -831,6 +872,9 @@ async function bundleClientComponents(globalRegistry, pagesDir, staticDir) {
   if (globalRegistry.size === 0) return /* @__PURE__ */ new Map();
   const outDir = path.join(staticDir, "__client-component");
   fs.mkdirSync(outDir, { recursive: true });
+  const workerOutDir = path.join(staticDir, "__worker");
+  const workerRegistry = new WorkerAssetRegistry({ outDir: workerOutDir, minify: true });
+  const workerPlugin = createWorkerUrlPlugin(workerRegistry);
   const entryPoints = {};
   for (const [id, filePath] of globalRegistry) {
     entryPoints[id] = filePath;
@@ -855,10 +899,14 @@ async function bundleClientComponents(globalRegistry, pagesDir, staticDir) {
     define: { "process.env.NODE_ENV": '"production"' },
     entryNames: "[name]",
     // cc_abc123.js (no hash on entries)
-    chunkNames: "__chunks/[hash]"
+    chunkNames: "__chunks/[hash]",
     // __chunks/ABCDEF.js
+    plugins: [workerPlugin]
   });
   console.log(`  bundled   ${globalRegistry.size} client component(s) \u2192 ${path.relative(process.cwd(), outDir)}/`);
+  if (workerRegistry.size > 0) {
+    console.log(`  bundled   ${workerRegistry.size} worker asset(s) \u2192 ${path.relative(process.cwd(), workerOutDir)}/`);
+  }
   const prerendered = /* @__PURE__ */ new Map();
   for (const [id, filePath] of globalRegistry) {
     const ssrTmp = path.join(
@@ -875,7 +923,13 @@ async function bundleClientComponents(globalRegistry, pagesDir, staticDir) {
         jsx: "automatic",
         packages: "external",
         define: { "process.env.NODE_ENV": '"production"' },
-        write: false
+        write: false,
+        // Same registry as Pass 1 — any worker already bundled there is
+        // reused from cache. Keeps this SSR-only bundle's source consistent
+        // with the browser bundle in case any worker-referencing code path
+        // is reachable during prerendering (it also means, if it ever is,
+        // `new URL(...)` won't throw for pointing at a moved temp file).
+        plugins: [workerPlugin]
       });
       fs.writeFileSync(ssrTmp, ssrResult.outputFiles[0].text);
       const { default: Component } = await import(pathToFileURL(ssrTmp).href);

package/dist/bundler.js

@@ -5,9 +5,11 @@ import { fileURLToPath } from "url";
 import { build } from "esbuild";
 import { log } from "./logger.js";
 import { getComponentCache } from "./component-analyzer.js";
+import { WorkerAssetRegistry, createWorkerUrlPlugin } from "./worker-assets.js";
 let reactBundlePromise = null;
 let nukeBundlePromise = null;
 const SPLIT_OUT_DIR = path.join(os.tmpdir(), "nukejs-dev-components");
+const WORKER_OUT_DIR = path.join(os.tmpdir(), "nukejs-dev-workers");
 let splitBuildValid = false;
 let splitBuildPromise = null;
 async function buildAllComponentsSplit() {
@@ -28,6 +30,7 @@ async function buildAllComponentsSplit() {
   }
   fs.mkdirSync(SPLIT_OUT_DIR, { recursive: true });
   log.verbose(`[bundler] Split build: ${clientComponents.size} component(s) \u2192 ${SPLIT_OUT_DIR}`);
+  const workerRegistry = new WorkerAssetRegistry({ outDir: WORKER_OUT_DIR, minify: false });
   await build({
     entryPoints,
     bundle: true,
@@ -49,9 +52,13 @@ async function buildAllComponentsSplit() {
     define: { "process.env.NODE_ENV": '"development"' },
     entryNames: "[name]",
     // cc_abc123.js (stable, no hash)
-    chunkNames: "__chunks/[hash]"
+    chunkNames: "__chunks/[hash]",
     // __chunks/ABCDEF.js
+    plugins: [createWorkerUrlPlugin(workerRegistry)]
   });
+  if (workerRegistry.size > 0) {
+    log.verbose(`[bundler] Bundled ${workerRegistry.size} worker asset(s) \u2192 ${WORKER_OUT_DIR}`);
+  }
   splitBuildValid = true;
   log.verbose("[bundler] Split build complete");
 }
@@ -85,6 +92,18 @@ async function serveClientComponentBundle(componentId, res) {
   res.setHeader("Content-Type", "application/javascript");
   res.end(fs.readFileSync(outPath));
 }
+async function serveWorkerAsset(fileName, res) {
+  const outPath = path.join(WORKER_OUT_DIR, fileName);
+  const base = WORKER_OUT_DIR.endsWith(path.sep) ? WORKER_OUT_DIR : WORKER_OUT_DIR + path.sep;
+  if (!outPath.startsWith(base) || !fs.existsSync(outPath)) {
+    log.error(`Worker asset not found: ${fileName}`);
+    res.statusCode = 404;
+    res.end("Worker asset not found");
+    return;
+  }
+  res.setHeader("Content-Type", "application/javascript");
+  res.end(fs.readFileSync(outPath));
+}
 async function serveReactBundle(res) {
   log.verbose("Bundling React runtime");
   if (!reactBundlePromise) {
@@ -157,5 +176,6 @@ export {
   invalidateSplitBundle,
   serveClientComponentBundle,
   serveNukeBundle,
-  serveReactBundle
+  serveReactBundle,
+  serveWorkerAsset
 };

package/dist/cache-store.js

@@ -0,0 +1,48 @@
+const KEY = /* @__PURE__ */ Symbol.for("__nukejs_cache_store__");
+const getGlobal = () => globalThis[KEY] ?? null;
+const setGlobal = (store) => {
+  globalThis[KEY] = store;
+};
+async function runWithCacheStore(fn) {
+  setGlobal({ entries: /* @__PURE__ */ new Map() });
+  try {
+    return await fn();
+  } finally {
+    setGlobal(null);
+  }
+}
+let cacheIdCounter = 0;
+function serialiseArgs(args) {
+  try {
+    return JSON.stringify(args, (_key, value) => {
+      if (typeof value === "function" || typeof value === "symbol") {
+        throw new Error("non-serialisable value");
+      }
+      return value;
+    });
+  } catch {
+    return null;
+  }
+}
+function cache(fn) {
+  const cacheId = `c${++cacheIdCounter}`;
+  return function cached(...args) {
+    const store = getGlobal();
+    if (!store) return fn(...args);
+    const argsKey = serialiseArgs(args);
+    if (argsKey === null) return fn(...args);
+    const key = `${cacheId}:${argsKey}`;
+    const existing = store.entries.get(key);
+    if (existing) return existing;
+    const result = fn(...args);
+    store.entries.set(key, result);
+    result.catch(() => {
+      store.entries.delete(key);
+    });
+    return result;
+  };
+}
+export {
+  cache,
+  runWithCacheStore
+};

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { default as useRouter } from './use-router';
 export { useRequest } from './use-request';
 export type { RequestContext } from './use-request';
 export { normaliseHeaders, sanitiseHeaders, getRequestStore } from './request-store';
+export { cache } from './cache-store';
 export { default as Link } from './Link';
 export { setupLocationChangeMonitor, initRuntime } from './bundle';
 export type { RuntimeData } from './bundle';

package/dist/index.js

@@ -3,6 +3,7 @@ import { useHtml } from "./use-html.js";
 import { default as default2 } from "./use-router.js";
 import { useRequest } from "./use-request.js";
 import { normaliseHeaders, sanitiseHeaders, getRequestStore } from "./request-store.js";
+import { cache } from "./cache-store.js";
 import { default as default3 } from "./Link.js";
 import { setupLocationChangeMonitor, initRuntime } from "./bundle.js";
 import { escapeHtml } from "./utils.js";
@@ -11,6 +12,7 @@ export {
   default3 as Link,
   ansi,
   c,
+  cache,
   createPersistedStore,
   createStore,
   escapeHtml,

package/dist/ssr.js

@@ -8,6 +8,7 @@ import { matchRoute, findLayoutsForRoute } from "./router.js";
 import { findClientComponentsInTree } from "./component-analyzer.js";
 import { renderElementToHtml } from "./renderer.js";
 import { runWithRequestStore, normaliseHeaders, sanitiseHeaders } from "./request-store.js";
+import { runWithCacheStore } from "./cache-store.js";
 import {
   runWithHtmlStore,
   resolveTitle
@@ -130,9 +131,9 @@ async function renderFile(filePath, params, url, pagesDir, isDev, res, req, stat
       query: queryParams,
       headers: normHeaders
     },
-    () => runWithHtmlStore(async () => {
+    () => runWithCacheStore(() => runWithHtmlStore(async () => {
       appHtml = await renderElementToHtml(wrappedElement, ctx);
-    })
+    }))
   );
   const pageTitle = resolveTitle(store.titleOps, "NukeJS");
   const headLines = [

package/dist/use-router.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 const SSR_ROUTER = { push: () => {
 }, replace: () => {
 }, back: () => {
@@ -28,7 +28,10 @@ function useRouter() {
   const refresh = useCallback(() => {
     window.dispatchEvent(new Event("locationchange"));
   }, []);
-  return { path, push, replace, back, refresh };
+  return useMemo(
+    () => ({ path, push, replace, back, refresh }),
+    [path, push, replace, back, refresh]
+  );
 }
 export {
   useRouter as default

package/dist/worker-assets.js

@@ -0,0 +1,151 @@
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+import { build } from "esbuild";
+import { log } from "./logger.js";
+const WORKER_URL_PREFIX = "/__worker/";
+const NEW_URL_RE = /new\s+URL\s*\(\s*(['"`])([^'"`]+)\1\s*,\s*import\.meta\.url\s*\)/g;
+const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs"];
+const URL_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+function isCandidateSpecifier(spec) {
+  if (spec.startsWith("/")) return false;
+  if (URL_SCHEME_RE.test(spec)) return false;
+  return true;
+}
+class WorkerAssetRegistry {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  built = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  /** Number of distinct worker assets bundled so far in this registry. */
+  get size() {
+    return this.built.size;
+  }
+  /**
+   * Resolves `rawSpecifier` (e.g. './parser.worker.ts', or a bare package
+   * specifier like 'monaco-editor/esm/.../json.worker.js') against the file
+   * that referenced it, bundling it on first use, and returns the public URL
+   * to substitute into the rewritten `new URL(...)` call.
+   *
+   * Returns null when the specifier isn't a candidate at all (see
+   * isCandidateSpecifier) or doesn't resolve to a real file on disk. The
+   * caller leaves the original expression untouched in that case — this is
+   * the mechanism that keeps non-local / dynamic `new URL(..., import.meta.url)`
+   * usages (including anything not meant to be a worker) working exactly as
+   * before.
+   */
+  async resolve(rawSpecifier, importerPath) {
+    if (!isCandidateSpecifier(rawSpecifier)) return null;
+    const absPath = resolveWorkerSpecifier(importerPath, rawSpecifier);
+    if (!absPath) return null;
+    const cached = this.built.get(absPath);
+    if (cached) return cached.publicUrl;
+    let inflight = this.pending.get(absPath);
+    if (!inflight) {
+      inflight = this.buildOne(absPath);
+      this.pending.set(absPath, inflight);
+    }
+    try {
+      const result = await inflight;
+      return result.publicUrl;
+    } finally {
+      this.pending.delete(absPath);
+    }
+  }
+  async buildOne(absPath) {
+    fs.mkdirSync(this.opts.outDir, { recursive: true });
+    log.verbose(`[worker-assets] bundling ${path.relative(process.cwd(), absPath)}`);
+    const result = await build({
+      entryPoints: [absPath],
+      bundle: true,
+      format: "esm",
+      platform: "browser",
+      target: "es2020",
+      jsx: "automatic",
+      minify: this.opts.minify,
+      write: true,
+      outdir: this.opts.outDir,
+      // esbuild computes [hash] from the output contents, so the filename
+      // — and therefore the emitted URL — changes automatically whenever the
+      // worker's own source (or anything it imports) changes. That's the
+      // "hashing/versioning" the rest of the framework's asset pipeline
+      // already relies on (see chunkNames in bundler.ts / build-common.ts).
+      entryNames: "[name]-[hash]",
+      metafile: true,
+      define: { "process.env.NODE_ENV": this.opts.minify ? '"production"' : '"development"' },
+      conditions: ["module", "browser", "import"]
+    });
+    const outputEntry = Object.entries(result.metafile.outputs).find(([, o]) => o.entryPoint);
+    if (!outputEntry) {
+      throw new Error(`[worker-assets] esbuild produced no output for ${absPath}`);
+    }
+    const outputPath = path.resolve(outputEntry[0]);
+    const publicUrl = WORKER_URL_PREFIX + path.basename(outputPath);
+    const info = { sourcePath: absPath, outputPath, publicUrl };
+    this.built.set(absPath, info);
+    log.verbose(`[worker-assets] ${path.relative(process.cwd(), absPath)} -> ${publicUrl}`);
+    return info;
+  }
+}
+function resolveWorkerSpecifier(importerPath, rawSpecifier) {
+  if (rawSpecifier.startsWith("./") || rawSpecifier.startsWith("../")) {
+    return resolveRelativeWorkerFile(path.dirname(importerPath), rawSpecifier);
+  }
+  return resolvePackageWorkerFile(importerPath, rawSpecifier);
+}
+function resolveRelativeWorkerFile(importerDir, rawSpecifier) {
+  const ext = path.extname(rawSpecifier);
+  const withoutExt = ext ? rawSpecifier.slice(0, -ext.length) : rawSpecifier;
+  const candidates = [rawSpecifier, ...RESOLVABLE_EXTENSIONS.map((e) => withoutExt + e)];
+  const tried = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    if (tried.has(candidate)) continue;
+    tried.add(candidate);
+    const abs = path.resolve(importerDir, candidate);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return abs;
+  }
+  return null;
+}
+function resolvePackageWorkerFile(importerPath, rawSpecifier) {
+  try {
+    const resolve = createRequire(importerPath).resolve;
+    const resolved = resolve(rawSpecifier);
+    return fs.existsSync(resolved) ? resolved : null;
+  } catch {
+    return null;
+  }
+}
+function createWorkerUrlPlugin(registry) {
+  return {
+    name: "nukejs-worker-url",
+    setup(pluginBuild) {
+      pluginBuild.onLoad({ filter: /\.[jt]sx?$/ }, async (args) => {
+        const source = await fs.promises.readFile(args.path, "utf8");
+        if (!source.includes("import.meta.url")) return null;
+        const matches = [...source.matchAll(NEW_URL_RE)];
+        if (matches.length === 0) return null;
+        let contents = source;
+        for (let i = matches.length - 1; i >= 0; i--) {
+          const match = matches[i];
+          const [full, , rawSpecifier] = match;
+          const publicUrl = await registry.resolve(rawSpecifier, args.path);
+          if (!publicUrl) continue;
+          const start = match.index;
+          const end = start + full.length;
+          const replacement = `new URL(${JSON.stringify(publicUrl)}, import.meta.url)`;
+          contents = contents.slice(0, start) + replacement + contents.slice(end);
+        }
+        if (contents === source) return null;
+        const ext = path.extname(args.path).slice(1);
+        const loader = ext === "ts" || ext === "tsx" || ext === "jsx" ? ext : "js";
+        return { contents, loader, resolveDir: path.dirname(args.path) };
+      });
+    }
+  };
+}
+export {
+  WORKER_URL_PREFIX,
+  WorkerAssetRegistry,
+  createWorkerUrlPlugin
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nukejs",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "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",