@jxsuite/compiler 7.0.0 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,12 @@
     "dist"
   ],
   "type": "module",
+  "imports": {
+    "#bundler-backend": {
+      "bun": "./src/site/bundler-backend.bun.ts",
+      "default": "./src/site/bundler-backend.node.ts"
+    }
+  },
   "exports": {
     ".": "./src/compiler.ts",
     "./asset-mounts": "./src/site/asset-mounts.ts",
@@ -30,7 +36,8 @@
     "./site": "./src/site/site-build.ts",
     "./site-loader": "./src/site/site-loader.ts",
     "./types": "./src/types.ts",
-    "./db-push": "./src/site/db-push.ts"
+    "./db-push": "./src/site/db-push.ts",
+    "./bundler": "./src/site/bundler.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -45,10 +52,10 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/create": "^1.4.1",
-    "@jxsuite/runtime": "^6.0.0",
-    "@jxsuite/schema": "^4.1.0",
-    "@jxsuite/site": "^2.2.1",
+    "@jxsuite/create": "^1.5.0",
+    "@jxsuite/runtime": "^6.0.1",
+    "@jxsuite/schema": "^5.0.0",
+    "@jxsuite/site": "^2.2.2",
     "@vue/reactivity": "3.5.44",
     "esbuild": "^0.28.2",
     "lit-html": "^3.3.3",
@@ -56,8 +63,8 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
-    "@jxsuite/connector": "^0.8.1",
-    "@jxsuite/parser": "^4.1.1",
+    "@jxsuite/connector": "^0.8.2",
+    "@jxsuite/parser": "^4.1.2",
     "@jxsuite/test-support": "^0.0.0",
     "@types/mdast": "^4.0.4"
   }

package/src/site/bundler-backend.bun.ts

@@ -0,0 +1,84 @@
+/**
+ * The Bun bundler backend: `Bun.build` and `Bun.resolveSync`. Selected by the `bun` condition of
+ * `#bundler-backend` (`bundler-backend.ts`), so only a Bun process ever loads this file.
+ *
+ * `JX_BUNDLER=esbuild` hands every call to the esbuild backend instead, so a parity check can run
+ * both under one Bun.
+ */
+import { rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { BuildConfig } from "bun";
+import type { BackendBuild, BundleTargetName } from "./bundler-backend.ts";
+import { TRANSIENT_ENTRY_PREFIX } from "./bundler-backend.ts";
+import * as esbuildBackend from "./bundler-backend.node.ts";
+
+/** True when this process was told to bundle with esbuild instead. */
+function forcedToEsbuild(): boolean {
+  return process.env.JX_BUNDLER === "esbuild";
+}
+
+/** Which bundler this backend runs. */
+export function backendName(): "bun" | "esbuild" {
+  return forcedToEsbuild() ? "esbuild" : "bun";
+}
+
+/** Resolve a bare specifier as an import from a module in `fromDir`. Throws when it does not. */
+export function resolveBare(specifier: string, fromDir: string): string {
+  if (forcedToEsbuild()) {
+    return esbuildBackend.resolveBare(specifier, fromDir);
+  }
+  return Bun.resolveSync(specifier, fromDir);
+}
+
+/** Map a bundle target to Bun.build's target. */
+function bunTarget(target: BundleTargetName): "browser" | "node" | "bun" {
+  if (target === "workerd") {
+    return "browser";
+  }
+  return target;
+}
+
+/** Bundle one file with `Bun.build` and return the output's text. */
+async function buildFile(entryPath: string, request: BackendBuild): Promise<string> {
+  const config: BuildConfig = {
+    entrypoints: [entryPath],
+    external: request.external,
+    format: "esm",
+    minify: request.minify,
+    plugins: request.plugins,
+    target: bunTarget(request.target),
+    throw: false,
+  };
+  if (request.conditions) {
+    config.conditions = request.conditions;
+  }
+  if (request.define) {
+    config.define = request.define;
+  }
+  const result = await Bun.build(config);
+  if (!result.success || result.outputs.length === 0) {
+    const logs = result.logs.map(String).join("\n");
+    throw new Error(`Bun.build failed for ${entryPath}:\n${logs}`);
+  }
+  return result.outputs[0]!.text();
+}
+
+/** Bundle to one ESM module and return its text. Throws with the backend's diagnostics on failure. */
+export async function build(request: BackendBuild): Promise<string> {
+  if (forcedToEsbuild()) {
+    return esbuildBackend.build(request);
+  }
+  const { entry } = request;
+  if ("path" in entry) {
+    return buildFile(entry.path, request);
+  }
+  // Bun.build has no stdin input: write a transient entry in `resolveDir` so resolution matches
+  // The stdin/resolveDir behaviour, and always remove it.
+  const entryPath = join(entry.resolveDir, `${TRANSIENT_ENTRY_PREFIX}${process.pid}.mjs`);
+  writeFileSync(entryPath, entry.source, "utf8");
+  try {
+    return await buildFile(entryPath, request);
+  } finally {
+    rmSync(entryPath, { force: true });
+  }
+}

package/src/site/bundler-backend.node.ts

@@ -0,0 +1,58 @@
+/**
+ * The esbuild bundler backend: the default of `#bundler-backend` (`bundler-backend.ts`), so every
+ * runtime that is not Bun bundles with it, and Bun does too under `JX_BUNDLER=esbuild`.
+ */
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type { BuildOptions } from "esbuild";
+import type { BackendBuild, BundleTargetName } from "./bundler-backend.ts";
+
+/** Which bundler this backend runs. */
+export function backendName(): "bun" | "esbuild" {
+  return "esbuild";
+}
+
+/** Resolve a bare specifier as an import from a module in `fromDir`. Throws when it does not. */
+export function resolveBare(specifier: string, fromDir: string): string {
+  return createRequire(join(fromDir, "package.json")).resolve(specifier);
+}
+
+/** Map a bundle target to esbuild's platform (conditions carry the workerd specifics). */
+function esbuildPlatform(target: BundleTargetName): "browser" | "node" {
+  return target === "node" || target === "bun" ? "node" : "browser";
+}
+
+/** Bundle to one ESM module and return its text. Throws with esbuild's diagnostics on failure. */
+export async function build(request: BackendBuild): Promise<string> {
+  // Dynamic import keeps esbuild (a native-binary dependency) off the load path until a bundle runs.
+  const esbuild = await import("esbuild");
+  const { entry } = request;
+  const options: BuildOptions = {
+    bundle: true,
+    external: request.external,
+    format: "esm",
+    logLevel: "silent",
+    minify: request.minify,
+    platform: esbuildPlatform(request.target),
+    plugins: request.plugins,
+    write: false,
+  };
+  if (request.conditions) {
+    options.conditions = request.conditions;
+  }
+  if (request.define) {
+    options.define = request.define;
+  }
+  if ("path" in entry) {
+    options.entryPoints = [entry.path];
+  } else {
+    options.stdin = {
+      contents: entry.source,
+      loader: "js",
+      resolveDir: entry.resolveDir,
+      sourcefile: "jx-entry.js",
+    };
+  }
+  const result = await esbuild.build({ ...options, write: false });
+  return result.outputFiles[0]!.text;
+}

package/src/site/bundler-backend.ts

@@ -0,0 +1,53 @@
+/**
+ * The contract between `bundler.ts` and the backend that does the bundling.
+ *
+ * The backend is chosen at **resolution time** by the `#bundler-backend` import's conditions
+ * (Node's conditional exports): `bundler-backend.bun.ts` under Bun, `bundler-backend.node.ts`
+ * (esbuild) everywhere else. A build of this package for Node therefore contains no Bun code at
+ * all, which is what lets the desktop backend run on Electron's Node (specs/desktop.md §7.1). Under
+ * Bun, `JX_BUNDLER=esbuild` still forces the esbuild backend for parity checks.
+ *
+ * `bundler.ts` owns everything both backends agree on (the defines, the minify default, the hook
+ * plugin); a backend owns only the call into its bundler and the spelling of its target.
+ */
+
+/** Resolution/runtime targets: client sidecars use "browser"; the site worker uses the rest. */
+export type BundleTargetName = "browser" | "node" | "bun" | "workerd";
+
+/**
+ * The part of a plugin builder the hooks use, typed so that both Bun's `PluginBuilder` and
+ * esbuild's `PluginBuild` are assignable to it: a plugin written against it is a plugin for either
+ * backend.
+ */
+export interface PluginBuild {
+  onResolve: (
+    options: { filter: RegExp },
+    callback: (args: {
+      path: string;
+      importer: string;
+    }) => { path: string; external: true } | undefined,
+  ) => void;
+  /** An `undefined` result hands the file back to the backend's own loader. */
+  onLoad: (options: { filter: RegExp }, callback: (args: { path: string }) => undefined) => void;
+}
+
+/** A plugin in the one shape both `Bun.build` and `esbuild.build` accept. */
+export interface BundlePlugin {
+  name: string;
+  setup: (build: PluginBuild) => void;
+}
+
+/** One bundle, with every option already decided by `bundler.ts`. */
+export interface BackendBuild {
+  /** A file to start from, or source text resolved as though it sat in `resolveDir`. */
+  entry: { path: string } | { source: string; resolveDir: string };
+  target: BundleTargetName;
+  external: string[];
+  conditions?: string[];
+  define?: Record<string, string>;
+  minify: boolean;
+  plugins: BundlePlugin[];
+}
+
+/** Basename prefix of the throwaway entry the Bun backend writes for a source entry. */
+export const TRANSIENT_ENTRY_PREFIX = ".jx-entry-";

package/src/site/bundler.ts

@@ -2,20 +2,30 @@
  * Bundler.js — timing-aware module bundling for compiled sites
  *
  * One backend abstraction serving every bundling need of the build (spec.md §12, compiler.md):
- * client-timing `$src` sidecars today, the server worker in a follow-up. Backend selection is
- * runtime-adaptive: `Bun.build` when the build runs under Bun, esbuild (dynamically imported) under
- * plain Node. Options are kept minimal and identical across backends so output stays as stable as
- * possible; set `JX_BUNDLER=esbuild` to force the fallback (e.g. for parity checks).
+ * client-timing `$src` sidecars today, the server worker in a follow-up. The backend is chosen at
+ * resolution time by the `#bundler-backend` import (`bundler-backend.ts`): `Bun.build` under Bun,
+ * esbuild everywhere else, so a Node build of this module carries no Bun code. Options are kept
+ * minimal and identical across backends so output stays as stable as possible; set
+ * `JX_BUNDLER=esbuild` to force esbuild under Bun (e.g. for parity checks).
  *
  * `timing: "compiler"` code is never bundled — it executes in the build host via the extension
  * registry's `importImplementation` path.
  */
 
 import { rmSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { isNpmSpecifier, NPM_SPECIFIER_PREFIX } from "@jxsuite/schema/asset-paths";
+import * as backend from "#bundler-backend";
+import type {
+  BackendBuild,
+  BundlePlugin,
+  BundleTargetName,
+  PluginBuild,
+} from "./bundler-backend.ts";
+import { TRANSIENT_ENTRY_PREFIX } from "./bundler-backend.ts";
+
+export type { BundleTargetName } from "./bundler-backend.ts";
 
 /** Import specifiers left external in client bundles — provided by the page importmap. */
 export const CLIENT_EXTERNALS = ["@vue/reactivity", "lit-html"];
@@ -29,11 +39,11 @@ export function isBundleableSrc(specifier: string): boolean {
 }
 
 /**
- * True when the Node code path (createRequire resolution, esbuild backend) should be used: always
- * under plain Node, or when `JX_BUNDLER=esbuild` forces it for parity checks.
+ * True when the esbuild backend is the one bundling: always outside Bun, or when
+ * `JX_BUNDLER=esbuild` forces it for parity checks.
  */
 export function useNodeFallback(): boolean {
-  return typeof Bun === "undefined" || process.env.JX_BUNDLER === "esbuild";
+  return backend.backendName() === "esbuild";
 }
 
 /**
@@ -47,15 +57,19 @@ export function resolveSidecarEntry(
   projectRoot: string,
 ): string {
   if (isNpmSpecifier(specifier)) {
-    const bare = specifier.slice(NPM_SPECIFIER_PREFIX.length);
-    if (useNodeFallback()) {
-      return createRequire(join(projectRoot, "package.json")).resolve(bare);
-    }
-    return Bun.resolveSync(bare, projectRoot);
+    return backend.resolveBare(specifier.slice(NPM_SPECIFIER_PREFIX.length), projectRoot);
   }
   return resolve(docDir, specifier);
 }
 
+/**
+ * Resolve a bare specifier as an import from a module in `fromDir`, through the active backend's
+ * resolver. Throws when it does not resolve.
+ */
+export function resolveBareSpecifier(specifier: string, fromDir: string): string {
+  return backend.resolveBare(specifier, fromDir);
+}
+
 export interface BundleRequest {
   /** Absolute path of the module to bundle. */
   entryPath: string;
@@ -63,9 +77,6 @@ export interface BundleRequest {
   outfile: string;
 }
 
-/** Resolution/runtime targets: client sidecars use "browser"; the site worker uses the rest. */
-export type BundleTargetName = "browser" | "node" | "bun" | "workerd";
-
 /**
  * A resolution hook, in the one shape both backends accept.
  *
@@ -110,26 +121,6 @@ export interface BundleOptions {
   onFileLoaded?: (path: string) => void;
 }
 
-/**
- * The part of a plugin builder the hooks use, typed so that both Bun's `PluginBuilder` and
- * esbuild's `PluginBuild` are assignable to it: a plugin written against it is a plugin for either
- * backend.
- */
-interface PluginBuild {
-  onResolve: (
-    options: { filter: RegExp },
-    callback: (args: { path: string; importer: string }) => ReturnType<BundleResolver["resolve"]>,
-  ) => void;
-  /** An `undefined` result hands the file back to the backend's own loader. */
-  onLoad: (options: { filter: RegExp }, callback: (args: { path: string }) => undefined) => void;
-}
-
-/** A plugin in the one shape both `Bun.build` and `esbuild.build` accept. */
-interface BundlePlugin {
-  name: string;
-  setup: (build: PluginBuild) => void;
-}
-
 /** Wrap the hooks as the one-plugin array both backends take. */
 function hookPlugins(opts: BundleOptions): BundlePlugin[] {
   const { onFileLoaded, resolver } = opts;
@@ -213,17 +204,15 @@ function sharedResolution(opts: BundleOptions): SharedResolution {
   return shared;
 }
 
-/** Map a bundle target to esbuild's platform (conditions carry the workerd specifics). */
-function esbuildPlatform(target: BundleTargetName): "browser" | "node" {
-  return target === "node" || target === "bun" ? "node" : "browser";
-}
-
-/** Map a bundle target to Bun.build's target. */
-function bunTarget(target: BundleTargetName): "browser" | "node" | "bun" {
-  if (target === "workerd") {
-    return "browser";
-  }
-  return target;
+/** Every option {@link BundleOptions} decides, in the shape a backend takes. */
+function backendOptions(opts: BundleOptions): Omit<BackendBuild, "entry"> {
+  return {
+    ...sharedResolution(opts),
+    external: opts.external ?? [],
+    minify: shouldMinify(opts),
+    plugins: hookPlugins(opts),
+    target: opts.target,
+  };
 }
 
 /**
@@ -231,46 +220,19 @@ function bunTarget(target: BundleTargetName): "browser" | "node" | "bun" {
  * diagnostics on failure.
  */
 export async function bundleEntry(request: BundleRequest, opts: BundleOptions): Promise<void> {
-  const external = opts.external ?? [];
-  const plugins = hookPlugins(opts);
-
-  if (useNodeFallback()) {
-    // Dynamic import keeps esbuild (a native-binary dependency) out of Bun-run builds entirely.
-    const esbuild = await import("esbuild");
-    await esbuild.build({
-      bundle: true,
-      ...sharedResolution(opts),
-      entryPoints: [request.entryPath],
-      external,
-      format: "esm",
-      logLevel: "silent",
-      minify: shouldMinify(opts),
-      outfile: request.outfile,
-      platform: esbuildPlatform(opts.target),
-      plugins,
-    });
-    return;
-  }
-
-  const result = await Bun.build({
-    ...sharedResolution(opts),
-    entrypoints: [request.entryPath],
-    external,
-    format: "esm",
-    minify: shouldMinify(opts),
-    plugins,
-    target: bunTarget(opts.target),
-    throw: false,
-  });
-  if (!result.success || result.outputs.length === 0) {
-    const logs = result.logs.map(String).join("\n");
-    throw new Error(`Bun.build failed for ${request.entryPath}:\n${logs}`);
-  }
-  writeFileSync(request.outfile, await result.outputs[0]!.text(), "utf8");
+  const code = await backend.build({ entry: { path: request.entryPath }, ...backendOptions(opts) });
+  writeFileSync(request.outfile, code, "utf8");
 }
 
-/** Basename prefix of the throwaway entry {@link bundleSource} writes for the Bun backend. */
-const TRANSIENT_ENTRY_PREFIX = ".jx-entry-";
+/**
+ * Bundle one entry module and return the code rather than writing it.
+ *
+ * For a host serving modules on demand (the dev server's and the desktop project server's bare
+ * specifier routes, the live preview's runtime): what it needs is the text for a response body.
+ */
+export async function bundleToString(entryPath: string, opts: BundleOptions): Promise<string> {
+  return backend.build({ entry: { path: entryPath }, ...backendOptions(opts) });
+}
 
 /**
  * True for the throwaway entry a {@link bundleSource} call is bundling, under either backend.
@@ -328,31 +290,8 @@ export async function bundleSource(
   { resolveDir, outfile }: { resolveDir: string; outfile: string },
   opts: BundleOptions,
 ): Promise<void> {
-  if (useNodeFallback()) {
-    const esbuild = await import("esbuild");
-    await esbuild.build({
-      bundle: true,
-      ...sharedResolution(opts),
-      external: opts.external ?? [],
-      format: "esm",
-      logLevel: "silent",
-      minify: shouldMinify(opts),
-      outfile,
-      platform: esbuildPlatform(opts.target),
-      stdin: { contents: source, loader: "js", resolveDir, sourcefile: "jx-entry.js" },
-    });
-    return;
-  }
-
-  // Bun.build has no stdin input — write a transient entry in `resolveDir` so resolution matches
-  // The stdin/resolveDir behavior, and always remove it.
-  const entryPath = join(resolveDir, `${TRANSIENT_ENTRY_PREFIX}${process.pid}.mjs`);
-  writeFileSync(entryPath, source, "utf8");
-  try {
-    await bundleEntry({ entryPath, outfile }, opts);
-  } finally {
-    rmSync(entryPath, { force: true });
-  }
+  const code = await backend.build({ entry: { resolveDir, source }, ...backendOptions(opts) });
+  writeFileSync(outfile, code, "utf8");
 }
 
 /**

package/src/site/client-runtime.ts

@@ -16,14 +16,13 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { dirname, join, relative, resolve } from "node:path";
 import type { BundleResolver } from "./bundler.ts";
 import {
   bundleSource,
   isTransientEntry,
+  resolveBareSpecifier,
   resolveThroughBundler,
-  useNodeFallback,
 } from "./bundler.ts";
 import { DEFAULT_LIT_HTML_SRC, DEFAULT_REACTIVITY_SRC } from "../shared.ts";
 import { isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
@@ -230,18 +229,14 @@ export function renderImportMap(imports: Record<string, string>): string {
 /**
  * True when a bare specifier resolves from `resolveDir` under either backend.
  *
- * The backend choice is `bundler.ts`'s to make, not a second inline `typeof Bun` check: resolution
- * and bundling must agree about which one they are on, or the import map promises a module the
- * bundle then fails to produce.
+ * The backend's own resolver answers, not a second inline choice: resolution and bundling must
+ * agree about which one they are on, or the import map promises a module the bundle then fails to
+ * produce.
  */
 function canResolve(specifier: string, resolveDir: string): boolean {
   try {
-    // Both resolvers throw when the specifier does not resolve, and return its path when it does.
-    if (useNodeFallback()) {
-      createRequire(join(resolveDir, "x.js")).resolve(specifier);
-    } else {
-      Bun.resolveSync(specifier, resolveDir);
-    }
+    // The resolver throws when the specifier does not resolve, and returns its path when it does.
+    resolveBareSpecifier(specifier, resolveDir);
     return true;
   } catch {
     return false;