chore(router): better error handling for SSG

Author: wmertens

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

@@ -202,34 +202,6 @@ export function viteAdapter(opts: ViteAdapterPluginOptions) {
                 `\n==============================================`
             );
           }
-          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/lightningcss@1.30.1/node_modules/lightningcss/node/index.js:20 - module.exports = require(`lightningcss-${parts.join('-')}`);
-             *
-             * # CustomGC
-             * ./node_modules/.pnpm/@tailwindcss+oxide@4.1.12/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/vite@7.1.2_@types+node@24.3.0_jiti@2.5.1_lightningcss@1.30.1_terser@5.43.1_tsx@4.20.4_yaml@2.8.1/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-city/src/static/main-thread.ts

@@ -80,13 +80,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);
+          });
         }
       };
 
@@ -134,6 +138,7 @@ export async function mainThread(sys: System) {
 
           flushQueue();
         } catch (e) {
+          console.error(`render failed for ${staticRoute.pathname}`, e);
           isCompleted = true;
           reject(e);
         }
@@ -216,8 +221,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);
     }
   });
@@ -244,6 +253,6 @@ function validateOptions(opts: StaticGenerateOptions) {
   try {
     new URL(siteOrigin);
   } catch (e) {
-    throw new Error(`Invalid "origin": ${e}`);
+    throw new Error(`Invalid "origin"`, { cause: e as Error });
   }
 }

packages/qwik-city/src/static/node/index.ts

@@ -1,6 +1,6 @@
 import type { StaticGenerateOptions } 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,20 @@ export async function generate(opts: StaticGenerateOptions) {
 }
 
 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') {
+        // eslint-disable-next-line no-console
+        console.debug(`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-city/src/static/node/node-main.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: StaticGenerateOptions) {
   const ssgWorkers: StaticGeneratorWorker[] = [];
@@ -51,28 +50,7 @@ export async function createNodeMainProcess(sys: System, opts: StaticGenerateOpt
     }
   }
 
-  const singleThreadWorker = await createSingleThreadWorker(sys);
-
-  const createWorker = (workerIndex: number) => {
-    if (workerIndex === 0) {
-      // same thread worker, don't start a new process
-      const ssgSameThreadWorker: StaticGeneratorWorker = {
-        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: StaticGenerateOpt
     }
 
     const nodeWorker = new Worker(workerFilePath, { workerData: opts });
-
+    nodeWorker.unref();
     const ssgWorker: StaticGeneratorWorker = {
       activeTasks: 0,
       totalTasks: 0,
@@ -223,7 +201,7 @@ export async function createNodeMainProcess(sys: System, opts: StaticGenerateOpt
   }
 
   for (let i = 0; i < maxWorkers; i++) {
-    ssgWorkers.push(createWorker(i));
+    ssgWorkers.push(createWorker());
   }
 
   const mainCtx: MainContext = {

packages/qwik-city/src/static/node/node-system.ts

@@ -8,9 +8,10 @@ import { createNodeWorkerProcess } from './node-worker';
 import { normalizePath } from '../../utils/fs';
 
 /** @public */
-export async function createSystem(opts: StaticGenerateOptions) {
-  patchGlobalThis();
-
+export async function createSystem(
+  opts: StaticGenerateOptions,
+  threadId?: number
+): Promise<System> {
   const createWriteStream = (filePath: string) => {
     return fs.createWriteStream(filePath, {
       flags: 'w',
@@ -29,6 +30,13 @@ export async function createSystem(opts: StaticGenerateOptions) {
   };
 
   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-city/src/static/node/node-worker.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-city/src/static/types.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: () => StaticGenerateOptions;
   ensureDir: (filePath: string) => Promise<void>;

packages/qwik-city/src/static/worker-thread.ts

@@ -15,28 +15,43 @@ import { _deserializeData, _serializeData, _verifySerializable } from '@builder.
 export async function workerThread(sys: System) {
   const ssgOpts = sys.getOptions();
   const pendingPromises = new Set<Promise<any>>();
+  const log = await sys.createLogger();
 
   const opts: StaticGenerateHandlerOptions = {
     ...ssgOpts,
+    // TODO export this from server
     render: (await import(pathToFileURL(ssgOpts.renderModulePath).href)).default,
-    qwikCityPlan: (await import(pathToFileURL(ssgOpts.qwikCityPlanModulePath).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<StaticWorkerRenderResult>((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<StaticWorkerRenderResult>((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) {
@@ -51,7 +66,9 @@ export async function createSingleThreadWorker(sys: System) {
 
   return (staticRoute: StaticRoute) => {
     return new Promise<StaticWorkerRenderResult>((resolve) => {
-      workerRender(sys, opts, staticRoute, pendingPromises, resolve);
+      workerRender(sys, opts, staticRoute, pendingPromises, resolve).catch((e) => {
+        console.error('Error during render', staticRoute.pathname, e);
+      });
     });
   };
 }
@@ -254,6 +271,13 @@ async function workerRender(
           }
         }
       })
+      .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);