chore(router): better error handling for SSG

Author: wmertens

packages/qwik-router/src/adapters/shared/vite/index.ts

@@ -232,34 +232,6 @@ export function viteAdapter(opts: ViteAdapterPluginOptions) {
               process.exit(0);
             }, 5000).unref();
           }
-          if (opts.ssg !== null) {
-            /**
-             * HACK: for some reason the build hangs after SSG. `why-is-node-running` shows 4
-             * culprits:
-             *
-             * ```
-             * There are 4 handle(s) keeping the process running.
-             *
-             * # CustomGC
-             * ./node_modules/.pnpm/[email protected]/node_modules/lightningcss/node/index.js:20 - module.exports = require(`lightningcss-${parts.join('-')}`);
-             *
-             * # CustomGC
-             * ./node_modules/.pnpm/@[email protected]/node_modules/@tailwindcss/oxide/index.js:229 - return require('@tailwindcss/oxide-linux-x64-gnu')
-             *
-             * # Timeout
-             * node_modules/.vite-temp/vite.config.timestamp-1755270314169-a2a97ad5233f9.mjs:357
-             * ./node_modules/.pnpm/[email protected]_@[email protected][email protected][email protected][email protected][email protected][email protected]/node_modules/vite/dist/node/chunks/dep-CMEinpL-.js:36657 - return (await import(pathToFileURL(tempFileName).href)).default;
-             *
-             * # CustomGC
-             * ./packages/qwik/dist/optimizer.mjs:1328 - const mod2 = module.default.createRequire(import.meta.url)(`../bindings/${triple.platformArchABI}`);
-             * ```
-             *
-             * For now, we'll force exit the process after SSG with some delay.
-             */
-            setTimeout(() => {
-              process.exit(0);
-            }, 5000).unref();
-          }
         }
       },
     },

packages/qwik-router/src/ssg/deno/index.ts

@@ -10,7 +10,7 @@ import type { SsgOptions, SsgRenderOptions, SsgResult } from './types';
  */
 export async function generate(opts: SsgOptions) {
   const ssgPlatform = await getEntryModule();
-  const result: SsgResult = (await ssgPlatform.generate(opts)) as any;
+  const result: SsgResult = await ssgPlatform.generate(opts);
   return result;
 }
 
@@ -20,27 +20,10 @@ export type {
   SsgResult as StaticGenerateResult,
 };
 
-function getEntryModule() {
-  if (isDeno()) {
-    return import('./deno');
+async function getEntryModule() {
+  try {
+    return await import('./node');
+  } catch (e) {
+    throw new Error(`Unsupported platform`, { cause: e });
   }
-  if (isBun() || isNode()) {
-    return import('./node');
-  }
-  throw new Error(`Unsupported platform`);
-}
-
-function isDeno() {
-  return typeof Deno !== 'undefined';
-}
-
-function isBun() {
-  return typeof Bun !== 'undefined';
-}
-
-function isNode() {
-  return !isBun() && !isDeno() && typeof process !== 'undefined' && !!process.versions?.node;
 }
-
-declare const Deno: any;
-declare const Bun: any;

packages/qwik-router/src/ssg/index.ts

@@ -81,13 +81,17 @@ export async function mainThread(sys: System) {
         while (!isCompleted && main.hasAvailableWorker() && queue.length > 0) {
           const staticRoute = queue.shift();
           if (staticRoute) {
-            render(staticRoute);
+            render(staticRoute).catch((e) => {
+              console.error(`render failed for ${staticRoute.pathname}`, e);
+            });
           }
         }
 
         if (!isCompleted && isRoutesLoaded && queue.length === 0 && active.size === 0) {
           isCompleted = true;
-          completed();
+          completed().catch((e) => {
+            console.error('SSG completion failed', e);
+          });
         }
       };
 
@@ -135,6 +139,7 @@ export async function mainThread(sys: System) {
 
           flushQueue();
         } catch (e) {
+          console.error(`render failed for ${staticRoute.pathname}`, e);
           isCompleted = true;
           reject(e);
         }
@@ -217,8 +222,12 @@ export async function mainThread(sys: System) {
         flushQueue();
       };
 
-      loadStaticRoutes();
+      loadStaticRoutes().catch((e) => {
+        console.error('SSG route loading failed', e);
+        reject(e);
+      });
     } catch (e) {
+      console.error('SSG main thread failed', e);
       reject(e);
     }
   });
@@ -251,6 +260,6 @@ function validateOptions(opts: SsgOptions) {
   try {
     new URL(siteOrigin);
   } catch (e) {
-    throw new Error(`Invalid "origin": ${e}`);
+    throw new Error(`Invalid "origin"`, { cause: e as Error });
   }
 }

packages/qwik-router/src/ssg/main-thread.ts

@@ -1,6 +1,6 @@
 import type { SsgOptions } from '../types';
 import { createSystem } from './node-system';
-import { isMainThread, workerData } from 'node:worker_threads';
+import { isMainThread, workerData, threadId } from 'node:worker_threads';
 import { mainThread } from '../main-thread';
 import { workerThread } from '../worker-thread';
 
@@ -15,9 +15,19 @@ export async function generate(opts: SsgOptions) {
 }
 
 if (!isMainThread && workerData) {
+  const opts = workerData as SsgOptions;
   (async () => {
-    // self initializing worker thread with workerData
-    const sys = await createSystem(workerData);
-    await workerThread(sys);
-  })();
+    try {
+      if (opts.log === 'debug') {
+        console.log(`Worker thread starting (ID: ${threadId})`);
+      }
+      // self initializing worker thread with workerData
+      const sys = await createSystem(opts, threadId);
+      await workerThread(sys);
+    } catch (error) {
+      console.error(`Error occurred in worker thread (ID: ${threadId}): ${error}`);
+    }
+  })().catch((e) => {
+    console.error(e);
+  });
 }

packages/qwik-router/src/ssg/node/index.ts

@@ -13,7 +13,6 @@ import { Worker } from 'node:worker_threads';
 import { dirname, extname, isAbsolute, join, resolve } from 'node:path';
 import { ensureDir } from './node-system';
 import { normalizePath } from '../../utils/fs';
-import { createSingleThreadWorker } from '../worker-thread';
 
 export async function createNodeMainProcess(sys: System, opts: SsgOptions) {
   const ssgWorkers: SsgWorker[] = [];
@@ -51,28 +50,7 @@ export async function createNodeMainProcess(sys: System, opts: SsgOptions) {
     }
   }
 
-  const singleThreadWorker = await createSingleThreadWorker(sys);
-
-  const createWorker = (workerIndex: number) => {
-    if (workerIndex === 0) {
-      // same thread worker, don't start a new process
-      const ssgSameThreadWorker: SsgWorker = {
-        activeTasks: 0,
-        totalTasks: 0,
-
-        render: async (staticRoute) => {
-          ssgSameThreadWorker.activeTasks++;
-          ssgSameThreadWorker.totalTasks++;
-          const result = await singleThreadWorker(staticRoute);
-          ssgSameThreadWorker.activeTasks--;
-          return result;
-        },
-
-        terminate: async () => {},
-      };
-      return ssgSameThreadWorker;
-    }
-
+  const createWorker = () => {
     let terminateResolve: (() => void) | null = null;
     const mainTasks = new Map<string, WorkerMainTask>();
 
@@ -98,7 +76,7 @@ export async function createNodeMainProcess(sys: System, opts: SsgOptions) {
     }
 
     const nodeWorker = new Worker(workerFilePath, { workerData: opts });
-
+    nodeWorker.unref();
     const ssgWorker: SsgWorker = {
       activeTasks: 0,
       totalTasks: 0,
@@ -223,7 +201,7 @@ export async function createNodeMainProcess(sys: System, opts: SsgOptions) {
   }
 
   for (let i = 0; i < maxWorkers; i++) {
-    ssgWorkers.push(createWorker(i));
+    ssgWorkers.push(createWorker());
   }
 
   const mainCtx: MainContext = {

packages/qwik-router/src/ssg/node/node-main.ts

@@ -7,7 +7,7 @@ import { createNodeWorkerProcess } from './node-worker';
 import { normalizePath } from '../../utils/fs';
 
 /** @public */
-export async function createSystem(opts: SsgOptions) {
+export async function createSystem(opts: SsgOptions, threadId?: number): Promise<System> {
   const createWriteStream = (filePath: string) => {
     return fs.createWriteStream(filePath, {
       flags: 'w',
@@ -26,6 +26,13 @@ export async function createSystem(opts: SsgOptions) {
   };
 
   const createLogger = async () => {
+    if (threadId !== undefined) {
+      return {
+        debug: opts.log === 'debug' ? console.debug.bind(console, `[${threadId}]`) : () => {},
+        error: console.error.bind(console, `[${threadId}]`),
+        info: console.info.bind(console, `[${threadId}]`),
+      };
+    }
     return {
       debug: opts.log === 'debug' ? console.debug.bind(console) : () => {},
       error: console.error.bind(console),

packages/qwik-router/src/ssg/node/node-system.ts

@@ -6,5 +6,8 @@ export async function createNodeWorkerProcess(
 ) {
   parentPort?.on('message', async (msg: WorkerInputMessage) => {
     parentPort?.postMessage(await onMessage(msg));
+    if (msg.type === 'close') {
+      parentPort?.close();
+    }
   });
 }

packages/qwik-router/src/ssg/node/node-worker.ts

@@ -6,7 +6,7 @@ export interface System {
   createMainProcess: (() => Promise<MainContext>) | null;
   createWorkerProcess: (
     onMessage: (msg: WorkerInputMessage) => Promise<WorkerOutputMessage>
-  ) => void;
+  ) => void | Promise<void>;
   createLogger: () => Promise<Logger>;
   getOptions: () => SsgOptions;
   ensureDir: (filePath: string) => Promise<void>;

packages/qwik-router/src/ssg/types.ts

@@ -22,35 +22,46 @@ export async function workerThread(sys: System) {
   delete (globalThis as any).__qwik;
   const ssgOpts = sys.getOptions();
   const pendingPromises = new Set<Promise<any>>();
+  const log = await sys.createLogger();
 
   const opts: SsgHandlerOptions = {
     ...ssgOpts,
+    // TODO export this from server
     render: (await import(pathToFileURL(ssgOpts.renderModulePath).href)).default,
+    // TODO this should be built-in
     qwikRouterConfig: (await import(pathToFileURL(ssgOpts.qwikRouterConfigModulePath).href))
       .default,
   };
 
-  sys.createWorkerProcess(async (msg) => {
-    switch (msg.type) {
-      case 'render': {
-        return new Promise<SsgWorkerRenderResult>((resolve) => {
-          workerRender(sys, opts, msg, pendingPromises, resolve);
-        });
-      }
-      case 'close': {
-        const promises = Array.from(pendingPromises);
-        pendingPromises.clear();
-        await Promise.all(promises);
-        return { type: 'close' };
+  sys
+    .createWorkerProcess(async (msg) => {
+      switch (msg.type) {
+        case 'render': {
+          log.debug(`Worker thread rendering: ${msg.pathname}`);
+          return new Promise<SsgWorkerRenderResult>((resolve) => {
+            workerRender(sys, opts, msg, pendingPromises, resolve).catch((e) => {
+              console.error('Error during render', msg.pathname, e);
+            });
+          });
+        }
+        case 'close': {
+          if (pendingPromises.size) {
+            log.debug(`Worker thread closing, waiting for ${pendingPromises.size} pending renders`);
+            const promises = Array.from(pendingPromises);
+            pendingPromises.clear();
+            await Promise.all(promises);
+          }
+          log.debug(`Worker thread closed`);
+          return { type: 'close' };
+        }
       }
-    }
-  });
+    })
+    ?.catch((e) => {
+      console.error('Worker process creation failed', e);
+    });
 }
 
 export async function createSingleThreadWorker(sys: System) {
-  // Special case: we allow importing qwik again in the same process, it's ok because we just needed the serializer
-  // TODO: remove this once we have vite environment API and no longer need the serializer separately
-  delete (globalThis as any).__qwik;
   const ssgOpts = sys.getOptions();
   const pendingPromises = new Set<Promise<any>>();
 
@@ -63,7 +74,9 @@ export async function createSingleThreadWorker(sys: System) {
 
   return (staticRoute: SsgRoute) => {
     return new Promise<SsgWorkerRenderResult>((resolve) => {
-      workerRender(sys, opts, staticRoute, pendingPromises, resolve);
+      workerRender(sys, opts, staticRoute, pendingPromises, resolve).catch((e) => {
+        console.error('Error during render', staticRoute.pathname, e);
+      });
     });
   };
 }
@@ -270,6 +283,13 @@ async function workerRender(
           console.error('Error during request handling', staticRoute.pathname, e);
         }
       })
+      .catch((e) => {
+        console.error('Unhandled error during request handling', staticRoute.pathname, e);
+        result.error = {
+          message: String(e),
+          stack: e.stack || '',
+        };
+      })
       .finally(() => {
         pendingPromises.delete(promise);
         callback(result);