apostrophe 4.30.0 → 4.31.0-alpha.1

package/modules/@apostrophecms/template/index.js

@@ -76,6 +76,32 @@ module.exports = {
     self.insertions = {};
     self.runtimeNodes = {};
 
+    // Install the .jsx require hook and teach the JSX runtime about
+    // Nunjucks' SafeString class so its instances pass through unescaped.
+    self.initJsx();
+
+    // Wire up the view-folder watcher with the two default invalidation
+    // handlers — Nunjucks loader caches and compiled .jsx modules. Both
+    // engines share a single set of chokidar watchers so we don't pay
+    // twice for watching the same directories.
+    const jsxLoader = require('./lib/jsxLoader.js');
+    self.onViewChange(function clearNunjucksLoaderCaches() {
+      // Setting `cache = {}` mirrors the historical in-loader behavior
+      // and is exactly what Nunjucks itself reads when looking up a
+      // previously-loaded template.
+      for (const loader of Object.values(self.loaders || {})) {
+        loader.cache = {};
+      }
+    });
+    self.onViewChange(function invalidateJsxModules(filePath) {
+      if (filePath && filePath.endsWith('.jsx')) {
+        jsxLoader.invalidate(path.resolve(filePath));
+      } else {
+        // Anything else (e.g. a Nunjucks file) might be a template imported
+        // by a `.jsx` file via require()/import — be safe and drop them all.
+        jsxLoader.invalidateAll();
+      }
+    });
   },
   handlers(self) {
     return {
@@ -117,9 +143,15 @@ module.exports = {
       },
       'apostrophe:destroy': {
         async nunjucksLoaderCleanup() {
+          // Older code paths used to manage chokidar watchers per loader;
+          // a no-op `destroy()` is still defined for backwards compat.
           for (const loader of Object.values(self.loaders || {})) {
             await loader.destroy();
           }
+        },
+        async closeViewWatchers() {
+          // Tear down chokidar watchers (Nunjucks + JSX share these).
+          await self.closeViewWatchers();
         }
       }
     };
@@ -127,6 +159,19 @@ module.exports = {
   methods(self) {
     return {
       ...require('./lib/bundlesLoader')(self),
+      ...require('./lib/jsxRender')(self),
+      ...require('./lib/viewWatcher')(self),
+
+      // Arm chokidar for the view-folder chain of the module whose views
+      // actually contain the resolved JSX file. For a same-module render
+      // that's the caller; for a cross-module render like
+      // `@apostrophecms/page` rendering `@apostrophecms/home-page:page`
+      // it's the target module. Idempotent per absolute directory.
+      watchJsxRenderTargets(callerModule, resolved) {
+        const owner = (resolved && self.apos.modules[resolved.moduleName]) ||
+          callerModule;
+        self.watchViewFolders(self.getViewFolders(owner));
+      },
 
       // Add helpers in the namespace for a particular module.
       // They will be visible in nunjucks at
@@ -261,6 +306,24 @@ module.exports = {
 
         let result;
 
+        // For named files, resolve through the module's view-folder
+        // chain. Chain position wins: a closer directory's .html/.njk
+        // beats a more distant directory's .jsx. JSX only takes
+        // precedence over Nunjucks within the same directory. See
+        // resolveTemplate. Falling back to Nunjucks happens automatically
+        // below when the resolved file is not JSX.
+        if (type === 'file') {
+          const resolved = self.resolveTemplate(module, s);
+          if (resolved && resolved.kind === 'jsx') {
+            const renderData = self.getRenderDataArgs(req, data, module);
+            result = await self.renderJsxTemplate(req, resolved, renderData, module);
+            if (process.platform === 'win32') {
+              result = result.replaceAll('\r', '');
+            }
+            return result;
+          }
+        }
+
         const args = self.getRenderArgs(req, data, module);
 
         const env = self.getEnv(req, module);
@@ -495,6 +558,9 @@ module.exports = {
         }
         if (!self.loaders[key]) {
           self.loaders[key] = self.newLoader(moduleName, dirs);
+          // Register these dirs with the shared view watcher (idempotent
+          // per absolute path, so calling it for every loader is fine).
+          self.watchViewFolders(dirs);
         }
         return self.loaders[key];
       },
@@ -1231,7 +1297,7 @@ module.exports = {
       async annotateDataForExternalFront(req, template, data, moduleName) {
         const docs = self.getDocsForExternalFront(req, template, data, moduleName);
         for (const doc of docs) {
-          self.annotateDocForExternalFront(doc, { scene: req.scene });
+          await self.annotateDocForExternalFront(doc, { scene: req.scene });
         }
         data.aposBodyData = await self.getBodyData(req);
         // Already contains module name too
@@ -1283,16 +1349,31 @@ module.exports = {
         ].filter(doc => !!doc);
       },
 
-      annotateDocForExternalFront(doc, { scene } = {}) {
+      async annotateDocForExternalFront(doc, { scene } = {}) {
+        const handled = new WeakSet();
+        const missingAreas = [];
         self.apos.doc.walk(doc, (o, k, v) => {
+          if (o._edit === true && !handled.has(o)) {
+            handled.add(o);
+            for (const field of self.missingSchemaAreas(o)) {
+              missingAreas.push([ o, field ]);
+            }
+          }
           if (v && v.metaType === 'area') {
-            const manager = self.apos.util.getManagerOf(o);
+            // A missing manager here is expected (e.g. an area reached on a
+            // container without a manager) and handled below, so suppress the
+            // low-level per-call log and rely on the once-per-process warning.
+            const manager = self.apos.util.getManagerOf(o, { log: false });
             if (!manager) {
-              self.apos.util.warnDevOnce('noManagerForDocInExternalFront', `No manager for: ${o.metaType} ${o.type || ''}`);
+              self.apos.util.warnDevOnce(
+                'noManagerForDocInExternalFront',
+                `No manager for: ${o.metaType} ${o.type || ''}`
+              );
               return;
             }
             const field = manager.schema.find(f => f.name === k);
             if (!field) {
+              v._isOrphan = true;
               self.apos.util.warnDevOnce(
                 'noSchemaFieldForAreaInExternalFront',
                 `Area ${k} has no matching schema field in ${o.metaType} ${o.type || ''}`
@@ -1302,6 +1383,14 @@ module.exports = {
             return self.annotateAreaForExternalFront(field, v, { scene });
           }
         });
+        // Materialize every missing area, after the walk so we never add keys
+        // to an object while it is being traversed.
+        for (const [ o, field ] of missingAreas) {
+          const area = await self.apos.area.addMissingArea(o, field.name);
+          area._edit = true;
+          area._docId = o._docId ?? (o.metaType === 'doc' ? o._id : null);
+          self.annotateAreaForExternalFront(field, area, { scene });
+        }
       },
 
       // Annotate an area for easy rendering by an external front end
@@ -1310,6 +1399,7 @@ module.exports = {
       // at least as an empty array.
 
       annotateAreaForExternalFront(field, area, { scene } = {}) {
+        area._aposAnnotated = true;
         area.field = field;
         area.options = field.options;
         // Really widget configurations, but the method name is already set in
@@ -1324,25 +1414,41 @@ module.exports = {
           };
         }).filter(choice => !!choice);
 
-        area.items ||= [];
+        // Drop corrupt items (null, or not a widget).
+        area.items = (area.items || []).filter((item) => {
+          const valid = item && item.metaType === 'widget' && item.type;
+          if (!valid) {
+            self.apos.util.warnDevOnce(
+              'corruptAreaItemInExternalFront',
+              `Dropping malformed item in area ${area._id || ''}`
+            );
+          }
+          return valid;
+        });
+
         for (const item of area.items) {
           // Add _docId if area has one
           if (area._docId) {
             item._docId = area._docId;
           }
 
-          // Annotate each individual widget with its options
-          // Each widget must elect into this by creating an
-          // `annotateWidgetForExternalFront() method.
+          // Annotate each individual widget with its options. Each widget must
+          // elect into this by creating an `annotateWidgetForExternalFront()`
+          // method.
           const manager = self.apos.area.getWidgetManager(item.type);
           if (manager) {
-            const widgetOptions = manager.annotateWidgetForExternalFront(item, { scene });
-            item._options = widgetOptions;
+            item._options = manager.annotateWidgetForExternalFront(item, { scene });
           } else {
             self.apos.area.warnMissingWidgetType(item.type);
-            throw self.apos.error('invalid', 'Missing widget type');
           }
         }
+      },
+
+      // The schema area fields of `object` that have no value yet. Returns an
+      // empty array for anything without a schema manager.
+      missingSchemaAreas(object) {
+        const schema = self.apos.util.getManagerOf(object, { log: false })?.schema ?? [];
+        return schema.filter(field => field.type === 'area' && !object[field.name]);
       }
     };
   }

package/modules/@apostrophecms/template/lib/jsxLoader.js

@@ -0,0 +1,128 @@
+// Compiles Apostrophe `.jsx` template files via Babel and registers a
+// `require.extensions['.jsx']` hook so they can be loaded with `require()`
+// (and `import` after CommonJS transformation) just like normal modules.
+//
+// Each compiled module is automatically prefixed with a `require()` of our
+// JSX runtime so the `h` and `Fragment` identifiers produced by the Babel
+// transform resolve without the user importing them. Both `import` and
+// `require` work inside `.jsx` files because the CommonJS transform also
+// runs.
+//
+// Source maps are kept in memory and wired through `source-map-support`,
+// which means stack traces from a JSX template point at the original
+// `views/page.jsx` line/column rather than the compiled output.
+
+const fs = require('fs');
+const Module = require('module');
+const babel = require('@babel/core');
+const sourceMapSupport = require('source-map-support');
+
+const runtimePath = require.resolve('./jsxRuntime.js');
+
+const sourceMaps = new Map();
+let installed = false;
+
+// Idempotent: register the require hook + source-map handler once per
+// process even if multiple Apostrophe instances boot in the same Node
+// process (e.g. tests, multisite).
+function install() {
+  if (installed) {
+    return;
+  }
+  installed = true;
+
+  sourceMapSupport.install({
+    environment: 'node',
+    hookRequire: false,
+    handleUncaughtExceptions: false,
+    retrieveSourceMap(filename) {
+      const map = sourceMaps.get(filename);
+      if (!map) {
+        return null;
+      }
+      return {
+        url: filename,
+        map
+      };
+    }
+  });
+
+  Module._extensions['.jsx'] = function(module, filename) {
+    const src = fs.readFileSync(filename, 'utf-8');
+    const compiled = compile(src, filename);
+    sourceMaps.set(filename, compiled.map);
+    module._compile(compiled.code, filename);
+  };
+}
+
+// Compile a JSX source string for `filename`. Returns `{ code, map }`.
+// `code` is CommonJS-compatible JS with our runtime injected at the top.
+function compile(src, filename) {
+  let result;
+  try {
+    result = babel.transformSync(src, {
+      filename,
+      sourceMaps: true,
+      sourceFileName: filename,
+      babelrc: false,
+      configFile: false,
+      compact: false,
+      plugins: [
+        [
+          require.resolve('@babel/plugin-transform-react-jsx'),
+          {
+            pragma: '__aposJsx.h',
+            pragmaFrag: '__aposJsx.Fragment',
+            useBuiltIns: false,
+            throwIfNamespace: false
+          }
+        ],
+        require.resolve('@babel/plugin-transform-modules-commonjs')
+      ]
+    });
+  } catch (e) {
+    // Babel errors already include code frames pointing at the offending
+    // line/column. Preserve that detail and add the file path for clarity.
+    const err = new Error(`JSX compile error in ${filename}: ${e.message}`);
+    err.cause = e;
+    err.code = 'APOS_JSX_COMPILE_ERROR';
+    err.filename = filename;
+    throw err;
+  }
+
+  // Inject runtime references. Using a single `__aposJsx` namespace avoids
+  // colliding with user variables named `h` or `Fragment` while still
+  // matching the pragma we passed to Babel above. Source maps remain valid
+  // because we only prepend a single line and rely on a leading `\n` to
+  // keep line numbers stable.
+  const prefix = `var __aposJsx = require(${JSON.stringify(runtimePath)});\n`;
+  return {
+    code: prefix + result.code,
+    map: result.map
+  };
+}
+
+// Drop a single .jsx file from the require cache and our source-map cache.
+// Called by the template module's chokidar watcher when a JSX file changes,
+// so the next render picks up the new code without restarting the process.
+function invalidate(filename) {
+  sourceMaps.delete(filename);
+  delete Module._cache[filename];
+}
+
+// Drop every cached .jsx module and source map. Used when watcher events
+// don't carry a specific path or when an unknown view file was modified.
+function invalidateAll() {
+  for (const filename of sourceMaps.keys()) {
+    delete Module._cache[filename];
+  }
+  sourceMaps.clear();
+}
+
+module.exports = {
+  install,
+  compile,
+  invalidate,
+  invalidateAll,
+  runtimePath
+};