feat: resolve external APIs in the local build (#211)

Author: jcbsfilho

lib/build/bundlers/esbuild/index.js

@@ -52,7 +52,7 @@ class Esbuild extends BundlerBase {
 
     if (useNodePolyfills) {
       if (!updatedConfig.plugins) updatedConfig.plugins = [];
-      updatedConfig.plugins.push(ESBuildNodeModulePlugin());
+      updatedConfig.plugins.push(ESBuildNodeModulePlugin(globalThis.buildProd));
     }
 
     // inject content in worker initial code.

lib/build/bundlers/esbuild/plugins/node-polyfills/index.js

@@ -4,10 +4,11 @@ import path from 'path';
 import PolyfillsManager from '../../../polyfills/polyfills-manager.js';
 
 /**
+ * @param {boolean} buildProd Parameter to identify whether the build is dev or prod
  * ESBuild Node Module Plugin for polyfilling node modules.
  * @returns {object} - ESBuild plugin object.
  */
-const ESBuildNodeModulePlugin = () => {
+const ESBuildNodeModulePlugin = (buildProd) => {
   const NAME = 'vulcan-node-modules-polyfills';
   const NAMESPACE = NAME;
 
@@ -43,13 +44,30 @@ const ESBuildNodeModulePlugin = () => {
         });
       }
 
+      // external
+      if (buildProd) {
+        options.external = options.external || [];
+        [...polyfillManager.external].forEach(([key]) => {
+          options.external.push(key);
+          options.external.push(`node:${key}`);
+        });
+      }
+
       /**
        * Resolve callback for ESBuild.
        * @param {object} args - Arguments object.
        * @returns {object|undefined} - Object with path and namespace or undefined.
        */
       build.onResolve({ filter: /.*/ }, async (args) => {
         const argsPath = args.path.replace(/^node:/, '');
+
+        if (!buildProd && polyfillManager.external.has(argsPath)) {
+          return {
+            path: args.path,
+            namespace: NAMESPACE,
+          };
+        }
+
         if (!polyfillManager.libs.has(argsPath)) {
           return;
         }
@@ -98,7 +116,12 @@ const ESBuildNodeModulePlugin = () => {
       build.onLoad({ filter: /.*/, namespace: NAMESPACE }, async (args) => {
         const argsPath = args.path.replace(/^node:/, '');
 
-        const resolved = polyfillManager.libs.get(argsPath);
+        let resolved = polyfillManager.libs.get(argsPath);
+
+        if (!buildProd && polyfillManager.external.has(argsPath)) {
+          resolved = polyfillManager.external.get(argsPath);
+        }
+
         const contents = await fs.promises.readFile(resolved, 'utf8');
         const resolveDir = path.dirname(resolved);
 

lib/build/bundlers/polyfills/polyfills-manager.js

@@ -7,6 +7,11 @@ const polyfillsPath = `${libDirPath}/build/bundlers/polyfills`;
 const nextNodePresetPath = `${libDirPath}/presets/custom/next/compute/node`;
 const nodePolyfillsPath = `${polyfillsPath}/node`;
 
+/**
+ * External polyfills are resolved in the build, but as they are for the local environment (Vulcan dev) they are located in #env/polyfills.
+ */
+const externalPolyfillsPath = `${libDirPath}/env/polyfills`;
+
 /**
  * Manages and builds polyfills for Node and global browser environments.
  */
@@ -21,6 +26,8 @@ class PolyfillsManager {
     this.libs = new Map();
     /** @type {Map<string, string|boolean>} */
     this.alias = new Map();
+    /** @type {Map<string, string|boolean>} */
+    this.external = new Map();
   }
 
   /**
@@ -50,9 +57,18 @@ class PolyfillsManager {
     this.alias.set(name, path);
   }
 
+  /**
+   * Sets a external libs.
+   * @param {string} name - Name of the external.
+   * @param {string|boolean} path - Path to the polyfill or a boolean value.
+   */
+  setExternal(name, path) {
+    this.external.set(name, path);
+  }
+
   /**
    * Builds and retrieves the polyfills for Node and globals.
-   * @returns {{ libs: Map<string, string|boolean>, globals: Map<string, string>, alias: Map<string, string> }} - Object containing libs and globals.
+   * @returns {{ libs: Map<string, string|boolean>, globals: Map<string, string>, alias: Map<string, string>, external: Map<string, string> }} - Object containing libs and globals.
    */
   buildPolyfills() {
     this.setGlobal('buffer', `${nodePolyfillsPath}/globals/buffer.js`);
@@ -70,7 +86,6 @@ class PolyfillsManager {
     );
 
     this.setLib('accepts', require.resolve('accepts'));
-    this.setLib('async_hooks', `${nodePolyfillsPath}/_empty.js`);
     this.setLib('buffer', require.resolve('buffer/'));
     this.setLib('child_process', `${nodePolyfillsPath}/_empty.js`);
     this.setLib('cluster', `${nodePolyfillsPath}/_empty.js`);
@@ -131,7 +146,17 @@ class PolyfillsManager {
     this.setAlias('util', require.resolve('util/'));
     this.setAlias('process', `${nodePolyfillsPath}/globals/process.js`);
 
-    return { libs: this.libs, globals: this.globals, alias: this.alias };
+    this.setExternal(
+      'async_hooks',
+      `${externalPolyfillsPath}/async_hooks/index.js`,
+    );
+
+    return {
+      libs: this.libs,
+      globals: this.globals,
+      alias: this.alias,
+      external: this.external,
+    };
   }
 }
 

lib/build/bundlers/polyfills/polyfills-manager.test.js

@@ -5,7 +5,6 @@ describe('Polyfills Manager', () => {
   it('Should return map of polyfills', () => {
     const expectedPolyfills = [
       'accepts',
-      'async_hooks',
       'buffer',
       'child_process',
       'cluster',

lib/build/bundlers/webpack/index.js

@@ -87,7 +87,7 @@ class Webpack extends BundlerBase {
       this.presetMode === 'compute';
 
     if (useNodePolyfills) {
-      updatedConfig.plugins.push(new NodePolyfillPlugin());
+      updatedConfig.plugins.push(new NodePolyfillPlugin(globalThis.buildProd));
     }
     return updatedConfig;
   }

lib/build/bundlers/webpack/plugins/node-polyfills/index.js

@@ -3,6 +3,10 @@ import { generateWebpackBanner } from '#utils';
 import PolyfillsManager from '../../../polyfills/polyfills-manager.js';
 
 class NodePolyfillPlugin {
+  constructor(buildProd) {
+    this.buildProd = buildProd;
+  }
+
   apply(compiler) {
     const polyfillsManager = PolyfillsManager.buildPolyfills();
 
@@ -46,6 +50,28 @@ class NodePolyfillPlugin {
       }),
     );
 
+    if (this.buildProd) {
+      compiler.options.externals = [
+        // eslint-disable-next-line
+        function ({ _, request }, callback) {
+          [...polyfillsManager.external].map(([key]) => {
+            const pattern = new RegExp(`${key}$`);
+            if (pattern.test(request)) {
+              return callback(null, `module ${request}`);
+            }
+            return callback();
+          });
+        },
+      ];
+    } else {
+      compiler.options.resolve.fallback = {
+        ...Object.fromEntries(
+          [...polyfillsManager.external].map(([key, value]) => [key, value]),
+        ),
+        ...compiler.options.resolve.fallback,
+      };
+    }
+
     compiler.options.resolve.alias = {
       ...Object.fromEntries(
         [...polyfillsManager.alias].map(([key, value]) => [key, value]),

lib/build/dispatcher/dispatcher.js

@@ -14,7 +14,7 @@ import {
   injectFilesInMem,
 } from '#utils';
 import { Messages } from '#constants';
-import { vulcan } from '#env';
+import vulcan from '../../env/vulcan.env.js';
 import {
   getAliasPath,
   createDotEnvFile,
@@ -378,6 +378,7 @@ class Dispatcher {
 
     await vulcan.createVulcanEnv(
       {
+        builder: builderSelected,
         entry: originalEntry, // original entry
         preset: buildConfig.preset.name,
         mode: buildConfig.preset.mode,

lib/commands/build.commands.js

@@ -1,6 +1,6 @@
 import { Commands } from '#namespaces';
 import { feedback } from '#utils';
-import { vulcan } from '#env';
+import vulcan from '../env/vulcan.env.js';
 
 /**
  * Retrieves a configuration value based on priority.

lib/constants/messages/env.messages.js

@@ -35,6 +35,7 @@ const env = {
     },
     errors: {
       load_worker_failed: (path) => `Failed load worker: ${path}`,
+      run_build_command: 'Run the build command before running your project',
     },
   },
 };

lib/env/polyfills/async_hooks/context/index.js

@@ -0,0 +1,10 @@
+/* eslint-disable */
+import * as async_hooks from 'async_hooks';
+
+export class AsyncLocalStorage extends async_hooks.AsyncLocalStorage {}
+export class AsyncResource extends async_hooks.AsyncResource {}
+
+export default {
+  AsyncLocalStorage,
+  AsyncResource,
+};

lib/env/polyfills/async_hooks/index.js

@@ -0,0 +1,12 @@
+/* eslint-disable */
+/**
+ * ASYNC_LOCAL_STORAGE is defined in runtime.env.js for use on the local server
+ */
+
+export class AsyncLocalStorage extends ASYNC_LOCAL_STORAGE.AsyncLocalStorage {}
+export class AsyncResource extends ASYNC_LOCAL_STORAGE.AsyncResource {}
+
+export default {
+  AsyncLocalStorage,
+  AsyncResource,
+};

lib/env/polyfills/FetchEvent.polyfills.js lib/env/polyfills/fetch/FetchEvent.polyfills.js

@@ -1,4 +1,5 @@
-import fetchPolyfill from './fetch.polyfills.js';
-import FetchEventPolyfill from './FetchEvent.polyfills.js';
+import fetchPolyfill from './fetch/fetch.polyfills.js';
+import FetchEventPolyfill from './fetch/FetchEvent.polyfills.js';
+import AsyncHooks from './async_hooks/context/index.js';
 
-export { fetchPolyfill, FetchEventPolyfill };
+export { fetchPolyfill, FetchEventPolyfill, AsyncHooks };

lib/env/polyfills/fetch.polyfills.js lib/env/polyfills/fetch/fetch.polyfills.js

@@ -1,6 +1,10 @@
 import { EdgeRuntime } from 'edge-runtime';
 
-import { fetchPolyfill, FetchEventPolyfill } from './polyfills/index.js';
+import {
+  fetchPolyfill,
+  FetchEventPolyfill,
+  AsyncHooks,
+} from './polyfills/index.js';
 
 /**
  * Executes the specified JavaScript code within a sandbox environment,
@@ -56,6 +60,9 @@ function runtime(code) {
     context.WebSocket = undefined;
     /* ========================================================== */
 
+    // Async Hooks
+    context.ASYNC_LOCAL_STORAGE = AsyncHooks;
+
     return context;
   };
 

lib/env/polyfills/fetch.polyfills.test.js lib/env/polyfills/fetch/fetch.polyfills.test.js

@@ -1,9 +1,10 @@
-import { debug, readWorkerFile, feedback, exec } from '#utils';
+import { debug, readWorkerFile, feedback } from '#utils';
 import { Messages } from '#constants';
 import { runServer, EdgeRuntime } from 'edge-runtime';
 import chokidar from 'chokidar';
 import runtime from './runtime.env.js';
 import vulcan from './vulcan.env.js';
+import buildCommand from '../commands/build.commands.js';
 
 let currentServer;
 let isChangeHandlerRunning = false;
@@ -37,13 +38,30 @@ async function initializeServer(port, workerCode) {
   return runServer({ port, host: '0.0.0.0', runtime: execution });
 }
 
+/**
+ * Build to Local Server with polyfill external
+ */
+async function buildToLocalServer() {
+  const vulcanEnv = await vulcan.readVulcanEnv('local');
+
+  if (!vulcanEnv) {
+    const msg = Messages.env.server.errors.run_build_command;
+    feedback.server.error(msg);
+    throw new Error(msg);
+  }
+  globalThis.buildProd = false;
+  await buildCommand({});
+}
+
 /**
  * Handle server operations: start, restart.
  * @param {string} workerPath - Path to the worker file.
  * @param {number} port - The port number.
  */
 async function manageServer(workerPath, port) {
   try {
+    await buildToLocalServer();
+
     const workerCode = await readWorkerCode(workerPath);
 
     if (currentServer) {
@@ -90,23 +108,8 @@ async function handleFileChange(path, workerPath, port) {
     return;
   }
 
-  const { entry, preset, mode, useNodePolyfills, useOwnWorker } =
-    await vulcan.readVulcanEnv('local');
-
-  let command = `vulcan build --entry ${entry} --preset ${preset} --mode ${mode}`;
-
-  if (useNodePolyfills) {
-    command += ` --useNodePolyfills ${useNodePolyfills}`;
-  }
-
-  if (useOwnWorker) {
-    command += ` --useOwnWorker ${useOwnWorker}`;
-  }
-
-  feedback.build.info(Messages.build.info.rebuilding);
-
   try {
-    await exec(command);
+    feedback.build.info(Messages.build.info.rebuilding);
     await manageServer(workerPath, port);
   } catch (error) {
     debug.error(`Build or server restart failed: ${error}`);

lib/env/polyfills/index.js

@@ -17,6 +17,9 @@ const vulcanVersion = vulcanPackageJSON.version;
 
 const debugEnabled = process.env.DEBUG === 'true';
 
+// This global variable is to define whether the build is for prod or dev. This is to handle external modules.
+globalThis.buildProd = true;
+
 const program = new Command();
 
 /**
@@ -88,6 +91,7 @@ function startVulcanProgram() {
     )
     .action(async (options) => {
       const { buildCommand } = await import('#commands');
+      globalThis.buildProd = true;
       await buildCommand(options);
     });
 

lib/env/runtime.env.js

@@ -116,6 +116,11 @@ class Manifest {
       JSON.stringify(this.manifest, null, 2),
       'utf8',
     );
+    // clear manifest to reload server
+    this.manifest = {
+      routes: [],
+      fs: [],
+    };
   }
 }