@zubra/unplugin 5.2.0 → 5.4.0

package/README.md

@@ -103,6 +103,10 @@ In Vite's dev server, editing a component **updates it in place**: the elements
 
 Components that import the edited one are recompiled too. Other bundlers' watch modes (Rollup, webpack) recompile on change.
 
+The dev server also compiles each component for the **Zubra DevTools** (`--devtools`): select a node in the browser's Elements panel and the Zubra pane shows its component's `.zb` file and line, its props and state, and each binding's line and the signals it reads (see `editors/devtools`). Builds carry none of it.
+
+To use the DevTools on a build too (a demo, a staging or preview deploy), pass `zubra({ devtools: true })` or set `ZUBRA_DEVTOOLS=1`: components are compiled the same way and `@zubra/runtime` resolves to its development build, which has the hook. It costs some bytes, so production builds leave it off by default.
+
 ## Tests
 
 `npm test` builds real React, Vue and plain Vite apps, runs them in Chromium, type-checks the generated typings with TypeScript, and checks the dev server, `build --watch` and error reporting. It needs a Rust toolchain (the compiler is built from this repository) and Playwright with Chromium.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zubra/unplugin",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "Compile .zb components in Vite, Rollup, webpack, esbuild and Rspack, with React and Vue wrappers picked automatically",
   "license": "ISC",
   "repository": {
@@ -34,8 +34,8 @@
     "unplugin": "3.7.0"
   },
   "peerDependencies": {
-    "@zubra/compiler": "^5.2.0",
-    "@zubra/runtime": "^5.2.0"
+    "@zubra/compiler": "^5.4.0",
+    "@zubra/runtime": "^5.4.0"
   },
   "devDependencies": {
     "@zubra/compiler": "file:../compiler",

package/src/index.js

@@ -26,6 +26,7 @@ import { spawnSync } from 'node:child_process';
 import { readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
 import { addProps, zubraImports } from './props.js';
 import { basename, dirname, extname, relative, resolve, sep } from 'node:path';
+import { createRequire } from 'node:module';
 
 const VARIANTS = ['element', 'react', 'vue'];
 /** A component file: `.zb`, or a JSX component (`.zb.jsx` / `.zb.tsx`). */
@@ -139,6 +140,10 @@ export const unplugin = createUnplugin((options = {}, meta = {}) => {
   const relativePath = (path) => path.startsWith(process.cwd()) ? path.slice(process.cwd().length + 1) : path;
   const compilerModule = options.compilerModule ?? '@zubra/compiler';
   let dev = false; // Vite's dev server: components hot-reload
+  // The Zubra DevTools in a build, not only in Vite's dev server: components compiled with
+  // --devtools, and @zubra/runtime's development build (which has the hook) instead of its
+  // production one. For demos, staging and previews; it costs bytes, so it's opt-in.
+  const devtoolsInBuilds = options.devtools ?? process.env.ZUBRA_DEVTOOLS === '1';
 
   /** CLI flags → a request for the WebAssembly compiler. */
   function asRequest(args) {
@@ -147,6 +152,7 @@ export const unplugin = createUnplugin((options = {}, meta = {}) => {
       const flag = args[i];
       if (flag === '--keep-imports') request.keepImports = true;
       else if (flag === '--no-imports') request.noImports = true;
+      else if (flag === '--devtools') request.devtools = true;
       else {
         const key = { '--emit': 'emit', '--framework': 'framework', '--runtime': 'runtime', '--css-import': 'cssImport', '--css-import-inline': 'cssImportInline' }[flag];
         if (!key) throw new Error(`zubra: unexpected compiler flag ${flag}`);
@@ -223,6 +229,14 @@ export const unplugin = createUnplugin((options = {}, meta = {}) => {
     },
 
     async resolveId(source, importer) {
+      // With devtools in builds: @zubra/runtime's development build, wherever it's imported from.
+      if (devtoolsInBuilds && /^@zubra\/runtime(\/|$)/.test(source)) {
+        const resolved = await this.resolve?.(source, importer, { skipSelf: true });
+        if (resolved && /[\\/]dist[\\/]production[\\/]/.test(resolved.id)) {
+          return { ...resolved, id: resolved.id.replace(/([\\/])dist[\\/]production([\\/])/, '$1src$2') };
+        }
+        return resolved;
+      }
       const [specifier, query] = split(source);
       if (!COMPONENT.test(specifier)) return null;
       let path;
@@ -292,11 +306,23 @@ export const unplugin = createUnplugin((options = {}, meta = {}) => {
       }
       let output;
       try {
-        output = compile(path, '--emit', 'js', '--keep-imports', '--runtime', runtime, ...styles);
+        // In Vite's dev server, what the browser DevTools panel reads: each part's place in the
+        // `.zb` file and the script's signals by name (the runtime's development build reads them).
+        const devtools = ((dev && meta.framework === 'vite') || devtoolsInBuilds) && !server ? ['--devtools'] : [];
+        output = compile(path, '--emit', 'js', '--keep-imports', '--runtime', runtime, ...styles, ...devtools);
       } catch (error) {
         return fail(this, error, path);
       }
       if (output.warnings) this.warn(output.warnings);
+      // 'use collection' compiles to an import of @zubra/sync: say what to install, rather than
+      // leave the bundler to report an unresolved import.
+      if (output.code.includes('from "@zubra/sync"')) {
+        try {
+          createRequire(path).resolve('@zubra/sync');
+        } catch {
+          return fail(this, new Error(`${relativePath(path)} starts with 'use collection', which needs @zubra/sync. Install it: npm install @zubra/sync`), path);
+        }
+      }
       if (server) return serverRendering ? output.code + serverRenderer(path, compilerModule, runtime) : output.code;
       return dev && meta.framework === 'vite' ? hot(output.code) : output.code;
     },