scalableminds · hotzenklotz · Jul 18, 2025 · Jul 21, 2025 · Jul 21, 2025 · Jul 21, 2025
diff --git a/.github/workflows/build_test_deploy.yml b/.github/workflows/build_test_deploy.yml
@@ -188,7 +188,7 @@ jobs:
         env:
           WK_VERSION: ${{ github.run_id }}
 
-      - name: Build webknossos (webpack)
+      - name: Build webknossos (esbuild)
         run: yarn build
 
       - name: Build webknossos (sbt)

diff --git a/app/views/main.scala.html b/app/views/main.scala.html
@@ -27,12 +27,6 @@
     <meta name="robot" content="noindex" />
     }
     <link rel="shortcut icon" type="image/png" href="/assets/images/favicon.png" />
-    <link
-      rel="stylesheet"
-      type="text/css"
-      media="screen"
-      href="/assets/bundle/vendors~main.css?nocache=@(webknossos.BuildInfo.commitHash)"
-    />
     <link
       rel="stylesheet"
       type="text/css"
@@ -44,8 +38,7 @@
       data-airbrake-project-key="@(conf.Airbrake.projectKey)"
       data-airbrake-environment-name="@(conf.Airbrake.environment)"
     ></script>
-    <script src="/assets/bundle/vendors~main.js?nocache=@(webknossos.BuildInfo.commitHash)"></script>
-    <script src="/assets/bundle/main.js?nocache=@(webknossos.BuildInfo.commitHash)"></script>
+    <script src="/assets/bundle/main.js?nocache=@(webknossos.BuildInfo.commitHash)" type="module"></script>
     <script type="text/javascript" src="https://app.olvy.co/script.js" defer="defer"></script>
   </head>
   <body>

diff --git a/esbuild_config.js b/esbuild_config.js
@@ -0,0 +1,228 @@
+const esbuild = require("esbuild");
+const path = require("node:path");
+const fs = require("node:fs");
+const os = require("node:os");
+
+const express = require("express");
+
+const app = express();
+
+const srcPath = path.resolve(__dirname, "frontend/javascripts/");
+const outputPath  = path.resolve(__dirname, "public/bundle/");
+const protoPath = path.join(__dirname, "webknossos-datastore/proto");
+
+// Community plugins
+const browserslistToEsbuild = require("browserslist-to-esbuild");
+const { lessLoader } = require("esbuild-plugin-less");
+const copyPlugin = require("esbuild-plugin-copy").default;
+const polyfillNode = require("esbuild-plugin-polyfill-node").polyfillNode;
+const esbuildPluginWorker = require("@chialab/esbuild-plugin-worker").default;
+const { wasmLoader } = require("esbuild-plugin-wasm");
+
+// Custom Plugins for Webknossos
+const { createWorkerPlugin } = require("./tools/esbuild/workerPlugin.js");
+const { createProtoPlugin } = require("./tools/esbuild/protoPlugin.js");
+
+const target = browserslistToEsbuild([
+  "last 3 Chrome versions",
+  "last 3 Firefox versions",
+  "last 2 Edge versions",
+  "last 1 Safari versions",
+  "last 1 iOS versions",
+]);
-const target = browserslistToEsbuild([
-  "last 3 Chrome versions",
-  "last 3 Firefox versions",
-  "last 2 Edge versions",
-  "last 1 Safari versions",
-  "last 1 iOS versions",
-]);
+const target = browserslistToEsbuild([
+  "last 6 Chrome versions",
+  "last 6 Firefox versions",
+  "last 4 Edge versions",
+  "last 2 Safari versions",
+  "last 2 iOS versions",
+]);
-const target = browserslistToEsbuild([
-  "last 3 Chrome versions",
-  "last 3 Firefox versions",
-  "last 2 Edge versions",
-  "last 1 Safari versions",
-  "last 1 iOS versions",
-]);
+const target = browserslistToEsbuild([
+  "last 6 Chrome versions",
+  "last 6 Firefox versions",
+  "last 4 Edge versions",
+  "last 2 Safari versions",
+  "last 2 iOS versions",
+]);
+
+function now() {
+  const d = new Date();
+  return d.toISOString().replace("T", " ").replace("Z", "");
+}
+
+async function build(env = {}) {
+  const isProduction = env.production || process.env.NODE_ENV === "production";
+  const isWatch = env.watch;
+
+  // Determine output directory for bundles.
+  // In watch mode, it's a temp dir. In production, it's the public bundle dir.
+  const buildOutDir = isWatch
+    ? path.join(os.tmpdir(), "webknossos-esbuild-dev")
+    : outputPath;
+
+  console.log("buildOutDir", buildOutDir);
+
+  if (isWatch) {
+    // Ensure a clean, stable directory for development builds
+    fs.rmSync(buildOutDir, { recursive: true, force: true });
+    fs.mkdirSync(buildOutDir, { recursive: true });
+  }
-  if (isWatch) {
-    // Ensure a clean, stable directory for development builds
-    fs.rmSync(buildOutDir, { recursive: true, force: true });
-    fs.mkdirSync(buildOutDir, { recursive: true });
-  }
+  if (isWatch) {
+    // Ensure a clean, stable directory for development builds
+    try {
+      fs.rmSync(buildOutDir, { recursive: true, force: true });
+      fs.mkdirSync(buildOutDir, { recursive: true });
+    } catch (error) {
+      console.error(`Failed to prepare build directory: ${error.message}`);
+      throw error;
+    }
+  }
-  if (isWatch) {
-    // Ensure a clean, stable directory for development builds
-    fs.rmSync(buildOutDir, { recursive: true, force: true });
-    fs.mkdirSync(buildOutDir, { recursive: true });
-  }
+  if (isWatch) {
+    // Ensure a clean, stable directory for development builds
+    try {
+      fs.rmSync(buildOutDir, { recursive: true, force: true });
+      fs.mkdirSync(buildOutDir, { recursive: true });
+    } catch (error) {
+      console.error(`Failed to prepare build directory: ${error.message}`);
+      throw error;
+    }
+  }
+
+  let onBuildDone = () => {}
+
+  // Track ongoing builds so that incoming requests can be paused until all builds are finished.
+  let currentBuildCount = 0;
+  let buildStartTime = null;
+  let buildCounterPlugin = {
+    name: 'buildCounterPlugin',
+    setup(build) {
+      build.onStart(() => {
+        if (currentBuildCount === 0) {
+          buildStartTime = performance.now();
+        }
+        currentBuildCount++;
+        console.log(now(), 'build started. currentBuildCount=', currentBuildCount)
+      })
+      build.onEnd(() => {
+        currentBuildCount--;
+        if (currentBuildCount === 0) {
+          console.log("Build took", performance.now() - buildStartTime);
+        }
+        console.log(now(), 'build ended. currentBuildCount=', currentBuildCount)
+        if (currentBuildCount === 0) {
+          onBuildDone();
+        }
+      })
+    },
+  }
+
+  const plugins = [
+    polyfillNode(),
+    createProtoPlugin(protoPath),
+    wasmLoader(),
+    lessLoader({
+      javascriptEnabled: true,
+    }),
+    copyPlugin({
+      patterns: [
+        {
+          from: "node_modules/@zip.js/zip.js/dist/z-worker.js",
+          to: path.join(buildOutDir, "z-worker.js"),
+        },
+      ],
+    }),
+    createWorkerPlugin({ logLevel: env.logLevel }), // Resolves import Worker from myFunc.worker;
+    esbuildPluginWorker(), // Resolves new Worker(myWorker.js)
+    buildCounterPlugin
+  ];
+
+
+  const buildOptions = {
+    entryPoints: {
+      main: path.resolve(srcPath, "main.tsx"),
+    },
+    bundle: true,
+    outdir: buildOutDir,
+    format: "esm",
+    target: target,
+    platform: "browser",
+    splitting: true,
+    chunkNames: "[name].[hash]",
+    assetNames: "[name].[hash]",
+    sourcemap: isProduction ? "external" : "inline",
+    minify: isProduction,
+    define: {
+      "process.env.NODE_ENV": JSON.stringify(isProduction ? "production" : "development"),
+      "process.env.BABEL_ENV": JSON.stringify(process.env.BABEL_ENV || "development"),
+      "process.browser": "true",
+      "global": "globalThis"
+    },
+    loader: {
+      ".woff": "file",
+      ".woff2": "file",
+      ".ttf": "file",
+      ".eot": "file",
+      ".svg": "file",
+      ".png": "file",
+      ".jpg": "file",
+      ".jpeg": "file",
+      ".gif": "file",
+      ".webp": "file",
+      ".ico": "file",
+      ".mp4": "file",
+      ".webm": "file",
+      ".ogg": "file",
+    },
+    resolveExtensions: [".ts", ".tsx", ".js", ".json", ".proto", ".wasm"],
+    alias: {
+      react: path.resolve(__dirname, "node_modules/react"),
+    },
+    plugins,
+    external: ["/assets/images/*", "fs"],
+    logLevel: env.logLevel || "info",
+    legalComments: isProduction ? "inline" : "none",
+    publicPath: "/assets/bundle/",
+    metafile: !isWatch, // Don't generate metafile for dev server
+    logOverride: {
+      "direct-eval": "silent",
+    },
+  };
+
+  if (env.watch) {
+    // Development server mode
+    const ctx = await esbuild.context(buildOptions);
+    const port = env.PORT || 9002;
+
+    // queue for waiting requests
+    let waiting = [];
+
+    function gateMiddleware(req, res, next) {
+      if (currentBuildCount === 0) {
+        return next(); // allow immediately
+      }
+
+      // hold request
+      waiting.push({ req, res, next });
+    }
-    function gateMiddleware(req, res, next) {
-      if (currentBuildCount === 0) {
-        return next(); // allow immediately
-      }
-
-      // hold request
-      waiting.push({ req, res, next });
-    }
+// queue for waiting requests
+let waiting = [];
+const MAX_QUEUE_SIZE = 1000;
+const QUEUE_TIMEOUT_MS = 30000;
+
+function gateMiddleware(req, res, next) {
+  if (currentBuildCount === 0) {
+    return next(); // allow immediately
+  }
+
+  if (waiting.length >= MAX_QUEUE_SIZE) {
+    res.status(503).send("Server too busy, please try again later");
+    return;
+  }
+
+  const timeout = setTimeout(() => {
+    const index = waiting.findIndex(w => w.req === req);
+    if (index !== -1) {
+      waiting.splice(index, 1);
+      res.status(504).send("Build timeout");
+    }
+  }, QUEUE_TIMEOUT_MS);
+
+  // hold request
+  waiting.push({ req, res, next, timeout });
+}
-    function gateMiddleware(req, res, next) {
-      if (currentBuildCount === 0) {
-        return next(); // allow immediately
-      }
-
-      // hold request
-      waiting.push({ req, res, next });
-    }
+// queue for waiting requests
+let waiting = [];
+const MAX_QUEUE_SIZE = 1000;
+const QUEUE_TIMEOUT_MS = 30000;
+
+function gateMiddleware(req, res, next) {
+  if (currentBuildCount === 0) {
+    return next(); // allow immediately
+  }
+
+  if (waiting.length >= MAX_QUEUE_SIZE) {
+    res.status(503).send("Server too busy, please try again later");
+    return;
+  }
+
+  const timeout = setTimeout(() => {
+    const index = waiting.findIndex(w => w.req === req);
+    if (index !== -1) {
+      waiting.splice(index, 1);
+      res.status(504).send("Build timeout");
+    }
+  }, QUEUE_TIMEOUT_MS);
+
+  // hold request
+  waiting.push({ req, res, next, timeout });
+}
+
+    app.use("/", gateMiddleware, express.static(buildOutDir));
+
+    onBuildDone = function releaseRequests() {
+      const queued = waiting;
+      waiting = [];
+      queued.forEach(({ next }) => {
+        return next();
+      });
+    }
+
+    app.listen(port, "127.0.0.1", () => {
+      console.log(`Server running at http://localhost:${port}/assets/bundle/`);
+    });
+
+    console.log(`Development server running at http://localhost:${port}`);
+    console.log(`Serving files from temporary directory: ${buildOutDir}`);
+
+    process.on("SIGINT", async () => {
+      await ctx.dispose();
+      process.exit(0);
+    });
-    process.on("SIGINT", async () => {
-      await ctx.dispose();
-      process.exit(0);
-    });
+    process.on("SIGINT", async () => {
+      console.log("\nShutting down development server...");
+      try {
+        await ctx.dispose();
+        console.log("Build context disposed successfully");
+      } catch (error) {
+        console.error("Error disposing build context:", error);
+      }
+      process.exit(0);
+    });
-    process.on("SIGINT", async () => {
-      await ctx.dispose();
-      process.exit(0);
-    });
+    process.on("SIGINT", async () => {
+      console.log("\nShutting down development server...");
+      try {
+        await ctx.dispose();
+        console.log("Build context disposed successfully");
+      } catch (error) {
+        console.error("Error disposing build context:", error);
+      }
+      process.exit(0);
+    });
+  } else {
+    // Production build
+    const result = await esbuild.build(buildOptions);
+
+    if (result.metafile) {
+      await fs.promises.writeFile(
+        path.join(buildOutDir, "metafile.json"),
+        JSON.stringify(result.metafile, null, 2)
+      );
+    }
+
+    console.log("Build completed successfully!");
+  }
+}
+
+module.exports = { build };
+
+// If called directly
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const env = {
+    logLevel: "info", // Default log level
+  };
+
+  args.forEach(arg => {
+    if (arg === "--production") env.production = true;
+    if (arg === "--watch") env.watch = true;
+    if (arg.startsWith("--port=")) env.PORT = Number.parseInt(arg.split("=")[1]);
+    if (arg === "--verbose") env.logLevel = "verbose";
+    if (arg === "--silent") env.logLevel = "silent";
+  });
+
+  build(env).catch(console.error);
+}
diff --git a/frontend/javascripts/libs/DRACOLoader.ts b/frontend/javascripts/libs/DRACOLoader.ts
@@ -237,7 +237,6 @@ class DRACOLoader extends Loader {
   _getWorker(taskID, taskCost) {
     return this._initDecoder().then(() => {
       if (this.workerPool.length < this.workerLimit) {
-        // See https://webpack.js.org/guides/web-workers/
         const worker = new Worker(new URL("./DRACOWorker.worker.js", import.meta.url));
 
         worker._callbacks = {};

diff --git a/frontend/javascripts/test/_ava_polyfill_provider.ts b/frontend/javascripts/test/_ava_polyfill_provider.ts
diff --git a/frontend/javascripts/viewer/model/helpers/reduce_reducers.ts b/frontend/javascripts/viewer/model/helpers/reduce_reducers.ts
@@ -2,7 +2,7 @@ import deepFreezeLib from "deep-freeze";
 import _ from "lodash";
 
 // Do not use the deep-freeze library in production
-// process.env.NODE_ENV is being substituted by webpack
+// process.env.NODE_ENV is being substituted by esbuild
 let deepFreeze = deepFreezeLib;
 if (process.env.NODE_ENV === "production") deepFreeze = _.identity;
 

diff --git a/frontend/javascripts/viewer/view/right-border-tabs/comment_tab/comment_tab_view.tsx b/frontend/javascripts/viewer/view/right-border-tabs/comment_tab/comment_tab_view.tsx
@@ -9,7 +9,7 @@ import {
 } from "@ant-design/icons";
 import { Tree as AntdTree, Dropdown, type GetRef, Space, Tooltip, type TreeProps } from "antd";
 import type { EventDataNode } from "antd/es/tree";
-import { useLifecycle } from "beautiful-react-hooks";
+import useLifecycle from "beautiful-react-hooks/useLifecycle";
 import { InputKeyboard } from "libs/input";
 import { useEffectOnlyOnce } from "libs/react_hooks";
 import { useWkSelector } from "libs/react_hooks";

diff --git a/frontend/javascripts/viewer/workers/comlink_wrapper.ts b/frontend/javascripts/viewer/workers/comlink_wrapper.ts
@@ -3,6 +3,14 @@ import {
   throwTransferHandlerWithResponseSupport,
 } from "viewer/workers/headers_transfer_handler";
 
+// Worker modules export bare functions and typically instantiated with new Worker("./path/to/my/worker.js");
+
+// JS bundlers (like esbuild) try to match these calls and generate new entry points/bundles for the worker code.
+// However, our esbuild pipeline is a bit different:
+// 1) We import our worker code with regular import statements, e.g. import worker from './my.worker';
+// 2) We consolidated all worker/Comlink stuff into this wrapper, calling new Worker(workerFunction). Since workerFunction is a variable it is usually not identified by esbuild as it matches not pattern.
+// Similar to the webpack worker-loader, we have a custom esbuild plugin to load worker codes. See tools/esbuild/workerPlugin.js.
+
 function importComlink() {
   const isNodeContext = typeof process !== "undefined" && process.title !== "browser";
 
@@ -36,8 +44,7 @@ const { wrap, transferHandlers, _expose, _transfer } = importComlink();
 transferHandlers.set("requestOptions", requestOptionsTransferHandler);
 // Overwrite the default throw handler with ours that supports responses.
 transferHandlers.set("throw", throwTransferHandlerWithResponseSupport);
-// Worker modules export bare functions, but webpack turns these into Worker classes which need to be
-// instantiated first.
+
 // To ensure that code always executes the necessary instantiation, we cheat a bit with the typing in the following code.
 // In reality, `expose` receives a function and returns it again. However, we tell flow that it wraps the function, so that
 // unwrapping becomes necessary.
@@ -47,18 +54,18 @@ type UseCreateWorkerToUseMe<T> = {
   readonly _wrapped: T;
 };
 export function createWorker<T extends (...args: any) => any>(
-  WorkerClass: UseCreateWorkerToUseMe<T>,
+  workerFunction: UseCreateWorkerToUseMe<T>,
 ): (...params: Parameters<T>) => Promise<ReturnType<T>> {
   if (wrap == null) {
     // In a node context (e.g., when executing tests), we don't create web workers which is why
     // we can simply return the input function here.
-    // @ts-ignore
-    return WorkerClass;
+    // @ts-expect-error
+    return workerFunction;
   }
 
   return wrap(
     // @ts-ignore
-    new WorkerClass(),
+    new Worker(workerFunction, { type: "module" }),
   );
 }
 export function expose<T>(fn: T): UseCreateWorkerToUseMe<T> {

diff --git a/frontend/javascripts/viewer/workers/readme.md b/frontend/javascripts/viewer/workers/readme.md
@@ -28,6 +28,6 @@ See `compress.worker.js` for an example.
 - Accessing global state (e.g., the Store) is not directly possible from web workers, since they have their own execution context. Pass necessary information into web workers via parameters.
 - By default, parameters and return values are either structurally cloned or transferred (if they support it) to/from the web worker. Copying is potentially performance-intensive and also won't propagate any mutations across the main-thread/webworker border. If objects are transferable (e.g., for ArrayBuffers, but not TypedArrays), they are moved to the new context, which means that they cannot be accessed in the old thread, anymore. In both cases, care has to be taken. In general, web workers should only be responsible for a very small (but cpu intensive) task with a bare minimum of dependencies.
 - Not all objects can be passed between main thread and web workers (e.g., Header objects). For these cases, you have to implement and register a specific transfer handler for the object type. See `headers_transfer_handler.js` as an example.
-- Web worker files can import NPM modules and also modules from within this code base, but beware that the execution context between the main thread and web workers is strictly isolated. Webpack will create a separate JS file for each web worker into which all imported code is compiled.
+- Web worker files can import NPM modules and also modules from within this code base, but beware that the execution context between the main thread and web workers is strictly isolated. esbuild will create a separate JS file for each web worker into which all imported code is compiled.
 
 Learn more about the Comlink module we use [here](https://github.com/GoogleChromeLabs/comlink).