PRO-6775: External frontend support, bugfix, debug mode (#10)

Author: myovchev

CHANGELOG.md

@@ -7,6 +7,13 @@
 * Adds postcss supports for the new `postcss-viewport-to-container-toggle` that allows the breakpoint preview feature to work.
 * Loads postcss config file from project only for public builds.
 * Adds `autoprefixer` plugin only for apos builds.
+* Adds module debug logs when in asset debug mode (`APOS_ASSET_DEBUG=1`).
+* Adds an option for disabling the module preload polyfill.
+* Adds support for `synthetic` entrypoints, that will only process the entrypoint `prologue`.
+
+### Fixes
+
+* Don't crash when there is no entrypoint of type `index`.
 
 ## 1.0.0-beta.1 (2024-10-31)
 

index.js

@@ -96,6 +96,7 @@ module.exports = {
       // see @apostrophecms/assset:getBuildOptions() for the options shape.
       // A required interface for the asset module.
       async build(options = {}) {
+        self.printDebug('build-options', { buildOptions: options });
         self.buildOptions = options;
         await self.buildBefore(options);
 
@@ -115,6 +116,7 @@ module.exports = {
       },
       // A required interface for the asset module.
       async startDevServer(options) {
+        self.printDebug('dev-server-build-options', { buildOptions: options });
         self.buildOptions = options;
         self.shouldCreateDevServer = true;
         await self.buildBefore(options);
@@ -124,7 +126,7 @@ module.exports = {
           build: currentBuild
         } = self.getCurrentMode(options.devServer);
 
-        self.entrypointsManifest.unshift(self.getViteClientEntrypoint(currentScenes));
+        self.ensureViteClientEntry(self.entrypointsManifest, currentScenes, options);
 
         let ts;
         if (currentBuild === 'public') {
@@ -151,9 +153,11 @@ module.exports = {
       },
       // A required interface for the asset module.
       // Initialize the watcher for triggering vite HMR via file
-      // copy to the build source.
+      // copy to the build source. This method is called always
+      // after the `startDevServer` method.
       // `chokidar` is a chockidar `FSWatcher` or compatible instance.
       async watch(chokidar, buildOptions) {
+        self.printDebug('watch-build-options', { buildOptions });
         self.buildWatchIndex();
         // Initialize our voting system to detect what entrypoints
         // are concerned with a given source file change.
@@ -175,12 +179,15 @@ module.exports = {
       // The options are same as the ones provided in the `build` and
       // `startDevServer` methods.
       async entrypoints(options) {
+        self.printDebug('entrypoints-build-options', { buildOptions: options });
         const entrypoints = self.apos.asset.getBuildEntrypoints(options.types)
           .filter(entrypoint => entrypoint.condition !== 'nomodule');
 
+        self.ensureInitEntry(entrypoints);
+
         if (options.devServer) {
           const { scenes } = self.getCurrentMode(options.devServer);
-          entrypoints.unshift(self.getViteClientEntrypoint(scenes));
+          self.ensureViteClientEntry(entrypoints, scenes, options);
         }
 
         return entrypoints;

lib/internals.js

@@ -11,6 +11,7 @@ const vitePostcssConfig = require('./vite-postcss-config');
 module.exports = (self) => {
   return {
     async initWhenReady() {
+      self.isDebug = self.apos.asset.isDebugMode();
       self.buildRoot = self.apos.asset.getBuildRootDir();
       self.buildRootSource = path.join(self.buildRoot, self.buildSourceFolderName);
       self.distRoot = path.join(self.buildRoot, self.distFolderName);
@@ -41,6 +42,12 @@ module.exports = (self) => {
       await fs.mkdir(self.buildRootSource, { recursive: true });
     },
 
+    printDebug(id, ...args) {
+      if (self.isDebug) {
+        self.logDebug('vite-' + id, ...args);
+      }
+    },
+
     async buildBefore(options = {}) {
       if (options.isTask) {
         await self.reset();
@@ -49,7 +56,8 @@ module.exports = (self) => {
         copyFiles: true
       });
       const entrypoints = self.apos.asset.getBuildEntrypoints(options.types);
-      self.applyModulePreloadPolyfill(entrypoints);
+      self.ensureInitEntry(entrypoints);
+      self.applyModulePreloadPolyfill(entrypoints, options);
       await self.createImports(entrypoints);
 
       // Copy the public files so that Vite is not complaining about missing files
@@ -77,6 +85,8 @@ module.exports = (self) => {
       await build(config);
       self.printLabels('apos', false);
 
+      self.printDebug('build-apos', { viteConfig: config });
+
       return Date.now();
     },
 
@@ -96,6 +106,8 @@ module.exports = (self) => {
       const { build, config } = await self.getViteBuild('public', options);
       await build(config);
       self.printLabels('public', false);
+
+      self.printDebug('build-public', { viteConfig: config });
     },
 
     // Create an entrypoint configuration for the vite client.
@@ -144,13 +156,6 @@ module.exports = (self) => {
       if (options.isTask || process.env.APOS_DEV === '1') {
         return true;
       }
-      // Forced build by type. Keeping the core current logic.
-      // In play when asset option `publicBundle: false` is set (forces ony apos build).
-      // Here we are only interested if we should force a "rebuild" or we can
-      // use the cache.
-      if (options.types?.includes(id)) {
-        return true;
-      }
       if (!self.hasViteBuildManifest(id)) {
         return true;
       }
@@ -163,6 +168,13 @@ module.exports = (self) => {
         return false;
       }
 
+      // Forced build by type. Keeping the core current logic.
+      // In play when asset option `publicBundle: false` is set - forces apos build
+      // if not cached.
+      if (options.types?.includes(id)) {
+        return true;
+      }
+
       return true;
     },
 
@@ -445,6 +457,8 @@ module.exports = (self) => {
       self.apos.util.log(
         `HMR for "${options.devServer}" started`
       );
+
+      self.printDebug('dev-middleware', { viteConfig });
     },
 
     // Compute metadata for the source files of all modules using
@@ -530,10 +544,19 @@ module.exports = (self) => {
 
     async getEntrypointOutput(entrypoint, suppressErrors = false) {
       const manager = self.apos.asset.getEntrypointManger(entrypoint);
-      const files = manager.getSourceFiles(
-        self.currentSourceMeta,
-        { composePath: self.composeSourceImportPath }
-      );
+
+      // synthetic entrypoints are not processed, they only provide
+      // a way to inject additional code (prologue) into the build.
+      const files = entrypoint.synthetic
+        ? entrypoint.outputs?.reduce((acc, ext) => ({
+          ...acc,
+          [ext]: []
+        }), {})
+        : manager.getSourceFiles(
+          self.currentSourceMeta,
+          { composePath: self.composeSourceImportPath }
+        );
+
       const output = await manager.getOutput(files, {
         modules: self.apos.asset.getRegisteredModules(),
         suppressErrors
@@ -543,13 +566,63 @@ module.exports = (self) => {
       return output;
     },
 
+    // Esnure there is always an `index` entrypoint, that holds the
+    // prologue and the scenes, required for the polyfill.
+    // The created synthetic entrypoint will only include the prologue.
+    ensureInitEntry(entrypoints) {
+      const exists = entrypoints.some((entry) => entry.type === 'index');
+      if (exists) {
+        return entrypoints;
+      }
+      const first = self.apos.asset.getBuildEntrypoints()
+        .find((entry) => entry.type === 'index');
+
+      const index = {
+        name: 'synth-src',
+        type: 'index',
+        // Synthetic entrypoints are not built, they only provide
+        // a way to inject additional code (prologue) into the build.
+        synthetic: true,
+        label: first.label,
+        scenes: first.scenes,
+        inputs: [],
+        outputs: [ 'js' ],
+        condition: first.condition,
+        prologue: first.prologue,
+        ignoreSources: [],
+        sources: {
+          js: [],
+          scss: []
+        }
+      };
+      entrypoints.unshift(index);
+
+      return entrypoints;
+    },
+
+    // Ensure Vite client is injected as a first entrypoint.
+    // This should be called after the `ensureInitEntry` method,
+    // basically as a last step. The method will add the Vite client
+    // entrypoint only if needed.
+    ensureViteClientEntry(entrypoints, scenes, buildOptions) {
+      if (buildOptions.devServer && !entrypoints.some((entry) => entry.name === 'vite')) {
+        entrypoints.unshift(self.getViteClientEntrypoint(scenes));
+      }
+    },
+
     // Add vite module preload polyfill to the first `index` entrypoint.
     // We can probably remove it soon as the browser support looks good:
     // https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/modulepreload#browser_compatibility
-    applyModulePreloadPolyfill(entrypoints) {
+    //
+    // The polyfill will be skipped for external frontends. External frontends
+    // are responsible for including the polyfill themselves if needed.
+    applyModulePreloadPolyfill(entrypoints, buildOptions) {
+      if (!buildOptions.modulePreloadPolyfill) {
+        return;
+      }
       const first = entrypoints.find((entry) => entry.type === 'index');
       first.prologue = (first.prologue || '') +
-        '\nimport \'vite/modulepreload-polyfill\';';
+          '\nimport \'vite/modulepreload-polyfill\';';
     },
 
     // Adds `manifest` property (object) to the entrypoint after a build.