@dom-expressions/jsx-compiler 0.50.0-next.16 → 0.50.0-next.18

package/README.md

@@ -15,6 +15,29 @@ matching your platform automatically through `optionalDependencies`. On other
 platforms, build from source with `pnpm run build` inside
 `packages/jsx-compiler` (requires a Rust toolchain).
 
+### WebAssembly and StackBlitz
+
+The compiler also ships a WASI fallback for environments such as StackBlitz
+WebContainers, where Node.js reports a native platform but cannot load `.node`
+addons. Enable the `wasm32` optional dependency when installing:
+
+```bash
+npm install --cpu=wasm32 @dom-expressions/jsx-compiler
+```
+
+With pnpm, add the installation architecture to `pnpm-workspace.yaml`:
+
+```yaml
+supportedArchitectures:
+  cpu:
+    - current
+    - wasm32
+```
+
+The normal package entry point prefers a native binding and falls back to
+`@dom-expressions/jsx-compiler-wasm32-wasi` when native addons are unavailable.
+Set `NAPI_RS_FORCE_WASI=error` to require the WASI binding for testing.
+
 ## Usage
 
 This package exposes a compiler backend API. It is not a Vite, Rollup, or Babel
@@ -136,8 +159,9 @@ Supported options track the Babel plugin where currently implemented:
 - `omitQuotes`
 - `omitAttributeSpacing`
 - `inlineStyles`
-- `effectWrapper`: `"effect"` or `false`
-- paired wrapperless mode: `wrapConditionals: false` with `memoWrapper: false`
+- `effectWrapper`: custom import name string, or `false` to disable
+- `memoWrapper`: custom import name string, or `false` to disable
+- `wrapConditionals`
 - `staticMarker`
 - `validate`
 - `omitNestedClosingTags`
@@ -146,6 +170,22 @@ Supported options track the Babel plugin where currently implemented:
 - `requireImportSource`
 - `renderers`
 
+## Performance
+
+Compared against `@dom-expressions/babel-plugin-jsx` compiling identical
+sources under identical options (Apple Silicon, release build, in-process,
+median of 7 iterations after warmup — run `pnpm bench` in this package to
+reproduce on your machine):
+
+| Workload                                        | babel-plugin-jsx | jsx-compiler | Speedup |
+| ----------------------------------------------- | ---------------: | -----------: | ------: |
+| Fixture corpus (88 files, 174 KB, all 10 modes) |           151 ms |       8.4 ms |     18x |
+| 129 KB single module                            |           230 ms |       4.6 ms |     50x |
+| 1 MB single module                              |        10,164 ms |        39 ms |    258x |
+
+Native throughput stays flat at ~20–27 MB/s as input grows, while Babel's
+per-file cost grows super-linearly — so the gap widens with file size.
+
 ## Current Scope
 
 This package is the AST-native compiler backend. It currently has checked fixture coverage for
@@ -159,10 +199,10 @@ the DOM, hydratable DOM, dev hydratable DOM, SSR, hydratable SSR, universal, dyn
   attribute handling covered by the checked fixture suites for those targets
 - Solid-compatible defaults such as `contextToCustomElements: true`
 - option coverage for `hydratable`, `dev`, `delegateEvents`, `delegatedEvents`,
-  `omitQuotes`, `omitAttributeSpacing`, `inlineStyles`, `effectWrapper: false`,
-  paired `wrapConditionals: false` / `memoWrapper: false`, `requireImportSource`,
-  `staticMarker`, `validate`, `omitNestedClosingTags`, `omitLastClosingTag`,
-  `builtIns`, and dynamic `renderers`
+  `omitQuotes`, `omitAttributeSpacing`, `inlineStyles`, `effectWrapper`,
+  `memoWrapper`, `wrapConditionals`, `requireImportSource`, `staticMarker`,
+  `validate`, `omitNestedClosingTags`, `omitLastClosingTag`, `builtIns`, and
+  dynamic `renderers`
 - source maps for the implemented path
 
 ## Not Implemented Yet
@@ -172,8 +212,6 @@ The compiler intentionally rejects unsupported features instead of pretending to
 - DOM `namespaceElements` sections that the current Oxc parser rejects before transform
   (for example, hyphenated JSX member segments)
 - arbitrary custom renderer names beyond dynamic DOM renderer override plus universal fallback
-- custom `effectWrapper` / `memoWrapper` helper names
-- unpaired `wrapConditionals: false` or `memoWrapper: false`
 - unknown/custom namespaced DOM attributes outside known runtime namespaces such as `xlink`
 
 ## Architecture
@@ -198,4 +236,3 @@ The module layout mirrors the Babel plugin shape where possible:
 - `src/ssr/transform.rs`
 - `src/universal/mod.rs`
 - `src/universal/transform.rs`
-

package/index.js

@@ -3,7 +3,7 @@
 const fs = require("fs");
 const path = require("path");
 
-const native = requireNative();
+const native = requireBinding();
 
 function transform(code, options) {
   if (typeof code !== "string") {
@@ -13,12 +13,6 @@ function transform(code, options) {
   }
 
   const nativeOptions = validateOptions(code, options);
-  if (nativeOptions?.skip) {
-    return {
-      code,
-      map: null
-    };
-  }
   const result = native.transform(code, nativeOptions);
   return {
     code: result.code,
@@ -46,6 +40,8 @@ const nativeOptionKeys = new Set([
   "effectWrapper",
   "wrapConditionals",
   "memoWrapper",
+  "requireImportSource",
+  "validate",
   "staticMarker",
   "omitNestedClosingTags",
   "omitLastClosingTag",
@@ -63,63 +59,40 @@ function validateOptions(code, options) {
     );
   }
 
-  const wrapperless = options.wrapConditionals === false || options.memoWrapper === false;
-  if (wrapperless) {
-    if (options.wrapConditionals !== false || options.memoWrapper !== false) {
-      throw new Error(
-        "@dom-expressions/jsx-compiler only supports wrapperless mode when `wrapConditionals: false` and `memoWrapper: false` are used together"
-      );
-    }
-  }
-
   const nativeOptions = {};
   for (const [key, value] of Object.entries(options)) {
-    if (key === "requireImportSource") {
-      if (value === false) continue;
-      if (typeof value !== "string") {
+    if (key === "effectWrapper" || key === "memoWrapper") {
+      if (typeof value !== "string" && typeof value !== "boolean") {
         throw new TypeError(
-          "@dom-expressions/jsx-compiler `requireImportSource` option must be false or a string"
+          `@dom-expressions/jsx-compiler \`${key}\` option must be a string import name or false`
         );
       }
-      if (!hasJsxImportSource(code, value)) {
-        return { skip: true };
-      }
+      nativeOptions[key] = value;
       continue;
     }
-    if (key === "effectWrapper") {
-      if (value === "effect") continue;
-      if (value === false) {
-        nativeOptions.effectWrapper = false;
-        continue;
+    if (key === "requireImportSource") {
+      if (value !== false && typeof value !== "string") {
+        throw new TypeError(
+          "@dom-expressions/jsx-compiler `requireImportSource` option must be false or a string"
+        );
       }
-      throw new Error(
-        '@dom-expressions/jsx-compiler only supports `effectWrapper: false` or the default `"effect"`'
-      );
+      if (value !== false) nativeOptions.requireImportSource = value;
+      continue;
     }
     if (key === "wrapConditionals") {
-      if (value === true) continue;
-      if (value === false) {
-        nativeOptions.wrapConditionals = false;
-        continue;
-      }
-      throw new TypeError(
-        "@dom-expressions/jsx-compiler `wrapConditionals` option must be boolean"
-      );
-    }
-    if (key === "memoWrapper") {
-      if (value === "memo") continue;
-      if (value === false) {
-        nativeOptions.memoWrapper = false;
-        continue;
+      if (typeof value !== "boolean") {
+        throw new TypeError(
+          "@dom-expressions/jsx-compiler `wrapConditionals` option must be boolean"
+        );
       }
-      throw new Error(
-        '@dom-expressions/jsx-compiler only supports `memoWrapper: false` or the default `"memo"`'
-      );
+      nativeOptions.wrapConditionals = value;
+      continue;
     }
     if (key === "validate") {
       if (typeof value !== "boolean") {
         throw new TypeError("@dom-expressions/jsx-compiler `validate` option must be boolean");
       }
+      nativeOptions.validate = value;
       continue;
     }
     if (nativeOptionKeys.has(key)) {
@@ -139,15 +112,6 @@ function validateOptions(code, options) {
   return nativeOptions;
 }
 
-function hasJsxImportSource(code, source) {
-  const pattern = /@jsxImportSource\s+([^\s*]+)/g;
-  let match;
-  while ((match = pattern.exec(code))) {
-    if (match[1] === source) return true;
-  }
-  return false;
-}
-
 function validateRenderers(renderers) {
   if (renderers == null) return;
   if (!Array.isArray(renderers)) {
@@ -188,10 +152,20 @@ function platformArchSuffix() {
   return null;
 }
 
-function requireNative() {
+function requireBinding() {
   const explicit = process.env.JSX_DOM_EXPRESSIONS_COMPILER_NATIVE;
   if (explicit) return require(explicit);
 
+  const forceWasi = process.env.NAPI_RS_FORCE_WASI;
+  if (forceWasi === "true" || forceWasi === "error") {
+    const wasi = requireWasi();
+    if (wasi) return wasi;
+    if (forceWasi === "error") {
+      throw new Error("WASI binding not found and NAPI_RS_FORCE_WASI is set to error");
+    }
+  }
+
+  let nativeError;
   const suffix = platformArchSuffix();
 
   // Local builds (napi build output) take precedence for development.
@@ -200,23 +174,63 @@ function requireNative() {
   localCandidates.push("jsx-compiler.node");
   for (const file of localCandidates) {
     const full = path.join(__dirname, file);
-    if (fs.existsSync(full)) return require(full);
+    if (fs.existsSync(full)) {
+      try {
+        return require(full);
+      } catch (error) {
+        nativeError = error;
+        break;
+      }
+    }
   }
 
-  if (suffix) {
+  if (!nativeError && suffix) {
+    const packageName = `@dom-expressions/jsx-compiler-${suffix}`;
     try {
-      return require(`@dom-expressions/jsx-compiler-${suffix}`);
+      return require(packageName);
     } catch (error) {
-      if (error.code !== "MODULE_NOT_FOUND") throw error;
+      if (!isMissingPackage(error, packageName)) nativeError = error;
     }
   }
 
+  const wasi = requireWasi();
+  if (wasi) return wasi;
+
+  if (nativeError) {
+    nativeError.message +=
+      "\nThe native binding could not be loaded and the optional " +
+      "@dom-expressions/jsx-compiler-wasm32-wasi fallback is not installed.";
+    throw nativeError;
+  }
+
   throw new Error(
-    `Could not find the native @dom-expressions/jsx-compiler binary for ${process.platform}-${process.arch}` +
+    `Could not find an @dom-expressions/jsx-compiler binding for ${process.platform}-${process.arch}` +
       (suffix
-        ? ` (expected the @dom-expressions/jsx-compiler-${suffix} package or a local build)`
+        ? ` (expected @dom-expressions/jsx-compiler-${suffix}, @dom-expressions/jsx-compiler-wasm32-wasi, or a local build)`
         : " (no prebuilt binary is published for this platform)") +
-      ". Run `pnpm run build` in packages/jsx-compiler to build from source."
+      ". Install with WASM support or run `pnpm run build` in packages/jsx-compiler."
+  );
+}
+
+function requireWasi() {
+  const localWasi = path.join(__dirname, "jsx-compiler.wasi.cjs");
+  if (fs.existsSync(localWasi)) return require(localWasi);
+
+  const packageName = "@dom-expressions/jsx-compiler-wasm32-wasi";
+  try {
+    return require(packageName);
+  } catch (error) {
+    if (!isMissingPackage(error, packageName)) throw error;
+    return null;
+  }
+}
+
+function isMissingPackage(error, packageName) {
+  return (
+    error &&
+    error.code === "MODULE_NOT_FOUND" &&
+    typeof error.message === "string" &&
+    error.message.includes(`'${packageName}'`)
   );
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dom-expressions/jsx-compiler",
   "description": "A JSX to DOM Expressions compiler implemented with Oxc",
-  "version": "0.50.0-next.16",
+  "version": "0.50.0-next.18",
   "author": "Ryan Carniato",
   "license": "MIT",
   "repository": {
@@ -31,22 +31,36 @@
       "aarch64-apple-darwin",
       "x86_64-unknown-linux-gnu",
       "aarch64-unknown-linux-gnu",
-      "x86_64-pc-windows-msvc"
-    ]
+      "x86_64-pc-windows-msvc",
+      "wasm32-wasip1-threads"
+    ],
+    "wasm": {
+      "browser": {
+        "fs": false,
+        "asyncInit": false,
+        "buffer": false,
+        "errorEvent": true
+      }
+    }
   },
   "devDependencies": {
-    "@napi-rs/cli": "^3.6.2"
+    "@emnapi/core": "^1.11.2",
+    "@emnapi/runtime": "^1.11.2",
+    "@napi-rs/cli": "^3.7.2",
+    "@napi-rs/wasm-runtime": "^1.1.6"
   },
   "optionalDependencies": {
-    "@dom-expressions/jsx-compiler-darwin-x64": "0.50.0-next.16",
-    "@dom-expressions/jsx-compiler-darwin-arm64": "0.50.0-next.16",
-    "@dom-expressions/jsx-compiler-linux-x64-gnu": "0.50.0-next.16",
-    "@dom-expressions/jsx-compiler-linux-arm64-gnu": "0.50.0-next.16",
-    "@dom-expressions/jsx-compiler-win32-x64-msvc": "0.50.0-next.16"
+    "@dom-expressions/jsx-compiler-darwin-x64": "0.50.0-next.18",
+    "@dom-expressions/jsx-compiler-darwin-arm64": "0.50.0-next.18",
+    "@dom-expressions/jsx-compiler-linux-x64-gnu": "0.50.0-next.18",
+    "@dom-expressions/jsx-compiler-linux-arm64-gnu": "0.50.0-next.18",
+    "@dom-expressions/jsx-compiler-win32-x64-msvc": "0.50.0-next.18",
+    "@dom-expressions/jsx-compiler-wasm32-wasi": "0.50.0-next.18"
   },
   "scripts": {
     "build": "napi build --release --strip --manifest-path ./Cargo.toml",
     "build:debug": "napi build --manifest-path ./Cargo.toml",
+    "bench": "pnpm run build && node scripts/bench.mjs",
     "lint": "cargo clippy --manifest-path ./Cargo.toml -- -D warnings",
     "test": "pnpm run build:debug && jest --no-cache",
     "artifacts": "napi artifacts",