@zubra/server 5.2.0 → 5.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zubra/server",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "Zubra on the server: render components into any template engine's pages, serve their browser modules, and give frameworks' HTML its components' shadow roots.",
   "type": "module",
   "main": "./src/index.js",
@@ -27,16 +27,23 @@
     "test": "node --test \"test/*.test.js\""
   },
   "peerDependencies": {
-    "@zubra/compiler": "^5.2.0",
-    "@zubra/runtime": "^5.2.0"
+    "@zubra/compiler": "^5.4.0",
+    "@zubra/runtime": "^5.4.0"
   },
   "devDependencies": {
+    "@minify-html/node": "0.18.1",
+    "@swc/html": "1.16.22",
     "@zubra/compiler": "file:../compiler",
     "@zubra/runtime": "file:../runtime",
+    "dompurify": "3.4.17",
     "express": "5.3.0",
     "fastify": "5.12.8",
     "hono": "4.13.17",
-    "playwright": "1.63.0"
+    "html-minifier-terser": "7.2.0",
+    "htmlnano": "3.6.1",
+    "jsdom": "31.0.0",
+    "playwright": "1.63.0",
+    "sanitize-html": "2.18.1"
   },
   "files": [
     "src"

package/src/index.d.ts

@@ -61,6 +61,11 @@ export interface ZubraOptions {
   cache?: boolean;
   /** Serve the runtime's production build, without hot reloading (default: `NODE_ENV` is `production`). */
   production?: boolean;
+  /**
+   * Compile for the Zubra DevTools extension and serve the runtime build it reads (default: on,
+   * except in production; `ZUBRA_DEVTOOLS=1` turns it on there too).
+   */
+  devtools?: boolean;
 }
 
 export declare function createZubra(options?: ZubraOptions): Zubra;

package/src/index.js

@@ -16,7 +16,8 @@
 // form-associated ones a hidden input, so the page is complete before JavaScript.
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
 import { StringDecoder } from 'node:string_decoder';
 import * as nodeStream from 'node:stream';
 const { Transform } = nodeStream;
@@ -36,16 +37,39 @@ const TYPES = { '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; char
  * `components`: the folder of `.zb` (and `.zb.jsx`/`.zb.tsx`) files. `prefix`: the URL path
  * the browser modules are served under. `cache`: keep compiled output (turn it off in
  * development to pick up edits). `production`: serve the runtime's production build, without hot
- * reloading (by default when `NODE_ENV` is `production`).
+ * reloading (by default when `NODE_ENV` is `production`). `devtools`: compile for the Zubra DevTools
+ * extension and serve the runtime build it reads (on by default except in production;
+ * `ZUBRA_DEVTOOLS=1` turns it on there too, for a demo or a staging site). `imports`: more import map entries,
+ * for packages the components import beyond `@zubra/runtime` and `@zubra/sync` (both of which
+ * are served and mapped by themselves).
  */
-export function createZubra({ components = 'components', prefix = '/_zubra', cache = true, production = process.env.NODE_ENV === 'production' } = {}) {
+export function createZubra({ components = 'components', prefix = '/_zubra', cache = true, production = process.env.NODE_ENV === 'production', devtools = process.env.ZUBRA_DEVTOOLS === '1' || !production, imports = {} } = {}) {
   const root = resolve(components);
   if (!existsSync(root)) throw new Error(`@zubra/server: no components folder at ${root}`);
   const sourceDir = dirname(fileURLToPath(import.meta.resolve('@zubra/runtime')));
   const productionDir = join(sourceDir, '..', 'dist', 'production');
-  const runtimeDir = production && existsSync(productionDir) ? productionDir : sourceDir;
+  // The Zubra DevTools need the runtime's development build, whose hook the production one leaves out.
+  const runtimeDir = production && !devtools && existsSync(productionDir) ? productionDir : sourceDir;
   const base = prefix.replace(/\/$/, '');
 
+  // @zubra/sync, for components that start with 'use collection': found from the components
+  // folder (the app's own node_modules), served under <prefix>/sync/ and put in the import map,
+  // so a page needs no setup for it. Not installed: such a component says so (`needs()`).
+  const syncDir = (() => {
+    for (const from of [join(root, 'noop.js'), join(process.cwd(), 'noop.js')]) {
+      try {
+        return dirname(createRequire(pathToFileURL(from)).resolve('@zubra/sync'));
+      } catch {}
+    }
+    return null;
+  })();
+  const needs = (name, code) => {
+    if (!syncDir && code.includes('from "@zubra/sync"')) {
+      throw new Error(`@zubra/server: ${relative(process.cwd(), pathOf(name))} starts with 'use collection', which needs @zubra/sync. Install it: npm install @zubra/sync`);
+    }
+    return code;
+  };
+
   // name (the path without its extension, "/"-separated) → file
   const files = new Map();
   (function walk(dir) {
@@ -86,13 +110,17 @@ export function createZubra({ components = 'components', prefix = '/_zubra', cac
     call(pathOf(name), { emit: 'html', props, slots, slotSource: 'html', partial: true, ...(pending.length ? { pending } : {}) });
   const css = (name) => once(`css:${name}`, () => call(pathOf(name), { emit: 'css' }));
   const js = (name) => once(`js:${name}`, () => {
-    const response = need().compileFile(pathOf(name), { emit: 'js', runtime: '@zubra/runtime' });
+    const response = need().compileFile(pathOf(name), { emit: 'js', runtime: '@zubra/runtime', devtools });
     if (!response.ok) throw new Error(response.error);
-    return response.output;
+    return needs(name, response.output);
   });
 
-  const importMap = () => `<script type="importmap">${JSON.stringify({ imports: { '@zubra/runtime': `${base}/runtime/index.js`, '@zubra/runtime/spread': `${base}/runtime/spread.js`, '@zubra/runtime/primitives': `${base}/runtime/primitives.js` } })}</script>`;
+  const importMap = () => `<script type="importmap">${JSON.stringify({ imports: { '@zubra/runtime': `${base}/runtime/index.js`, '@zubra/runtime/spread': `${base}/runtime/spread.js`, '@zubra/runtime/primitives': `${base}/runtime/primitives.js`, ...syncImports, ...imports } })}</script>`;
+  const syncImports = syncDir ? { '@zubra/sync': `${base}/sync/index.js`, '@zubra/sync/connect': `${base}/sync/connect.js` } : {};
   const head = (names) => {
+    // A component that needs a package that isn't installed fails here, while the page is built,
+    // with the reason, rather than later in the browser as an unresolved import.
+    for (const name of names) js(name);
     const styles = names.map(css).join('\n');
     return `${styles ? `<style data-zb-components>${styles}</style>\n` : ''}${importMap()}`;
   };
@@ -107,6 +135,11 @@ export function createZubra({ components = 'components', prefix = '/_zubra', cac
       if (!files.has(name)) return { status: 404, type: 'text/plain', body: 'Not found' };
       return { status: 200, type: TYPES['.js'], body: js(name) };
     }
+    if (rest.startsWith('sync/') && syncDir) {
+      const file = resolve(syncDir, rest.slice('sync/'.length));
+      if (!file.startsWith(syncDir + sep) || extname(file) !== '.js' || !existsSync(file)) return { status: 404, type: 'text/plain', body: 'Not found' };
+      return { status: 200, type: TYPES['.js'], body: readFileSync(file) };
+    }
     if (rest.startsWith('runtime/')) {
       const file = resolve(runtimeDir, rest.slice('runtime/'.length));
       if (!file.startsWith(runtimeDir + sep) || !existsSync(file) || statSync(file).isDirectory()) return { status: 404, type: 'text/plain', body: 'Not found' };
@@ -296,6 +329,7 @@ export function createZubra({ components = 'components', prefix = '/_zubra', cac
       writeFileSync(file, js(name));
     }
     cpSync(runtimeDir, join(out, 'runtime'), { recursive: true });
+    if (syncDir) cpSync(syncDir, join(out, 'sync'), { recursive: true, filter: (from) => !from.endsWith('.d.ts') });
   }
 
   /**