web: Fix ESBuild hanging process (#18162)

Author: GirlBossRush

web/bundler/style-loader-plugin/node.js

@@ -1,12 +1,15 @@
 /**
  * @file MDX plugin for ESBuild.
  *
- * @import { Plugin, PluginBuild, BuildContext } from "esbuild"
+ * @import { Plugin, PluginBuild, BuildContext, BuildOptions } from "esbuild"
+ * @import { BaseLogger } from "pino"
  */
 
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
+
+import { ConsoleLogger } from "#logger/node";
 
 import { resolvePackage } from "@goauthentik/core/paths/node";
 
@@ -16,12 +19,23 @@ const CSSNamespace = /** @type {const} */ ({
     Bundled: "css-bundled",
 });
 
+/**
+ * @typedef StyleLoaderPluginOptions
+ *
+ * @property {boolean} [watch] Whether to watch for file changes.
+ * @property {BaseLogger} [logger]
+ */
+
 /**
  * Selectively apply the ESBuild `css` loader.
  *
+ * @param {StyleLoaderPluginOptions} [options]
  * @returns {Plugin}
  */
-export function styleLoaderPlugin() {
+export function styleLoaderPlugin({
+    watch = false,
+    logger = ConsoleLogger.child({ name: "style-loader-plugin" }),
+} = {}) {
     const patternflyPath = resolvePackage("@patternfly/patternfly", import.meta);
     const require = createRequire(import.meta.url);
 
@@ -56,7 +70,8 @@ export function styleLoaderPlugin() {
             const disposables = new Map();
 
             build.onDispose(async () => {
-                for (const ctx of disposables.values()) {
+                for (const [filePath, ctx] of disposables) {
+                    logger.debug(`Disposing CSS build context for ${filePath}`);
                     await ctx.dispose();
                 }
             });
@@ -114,33 +129,50 @@ export function styleLoaderPlugin() {
                 const cssContent = await readFile(args.path, "utf8");
                 let context = disposables.get(args.path);
 
-                if (!context) {
-                    context = await build.esbuild.context({
-                        stdin: {
-                            contents: cssContent,
-                            resolveDir: dirname(args.path),
-                            loader: "css",
-                        },
-                        metafile: true,
-                        bundle: true,
-                        write: false,
-                        minify: build.initialOptions.minify || false,
-                        logLevel: "silent",
-                        loader: { ".woff": "empty", ".woff2": "empty" },
-                        plugins: [
-                            {
-                                name: "font-resolver",
-                                setup(fontBuild) {
-                                    fontBuild.onResolve(...fontResolverArgs);
-                                },
+                /**
+                 * @type {BuildOptions}
+                 */
+                const buildOptions = {
+                    stdin: {
+                        contents: cssContent,
+                        resolveDir: dirname(args.path),
+                        loader: "css",
+                    },
+                    metafile: true,
+                    bundle: true,
+                    write: false,
+                    minify: build.initialOptions.minify || false,
+                    logLevel: "silent",
+                    loader: { ".woff": "empty", ".woff2": "empty" },
+                    plugins: [
+                        {
+                            name: "font-resolver",
+                            setup(fontBuild) {
+                                fontBuild.onResolve(...fontResolverArgs);
                             },
-                        ],
-                    });
+                        },
+                    ],
+                };
 
-                    disposables.set(args.path, context);
+                if (!watch) {
+                    const result = await build.esbuild.build(buildOptions);
+                    const bundledCSS = result.outputFiles?.[0].text;
+
+                    return {
+                        contents: bundledCSS,
+                        loader: "text",
+                    };
                 }
 
-                await context.cancel();
+                if (!context) {
+                    const relativePath = relative(absWorkingDir, args.path);
+                    logger.debug(`Watching ${relativePath}`);
+                    context = await build.esbuild.context(buildOptions);
+
+                    disposables.set(args.path, context);
+                } else {
+                    await context.cancel();
+                }
 
                 // Resolve the CSS content by bundling it with ESBuild.
                 const result = await context.rebuild();

web/paths/node.js

@@ -9,8 +9,6 @@ import { fileURLToPath } from "node:url";
 
 import { DistDirectoryName } from "#paths";
 
-import { resolvePackage } from "@goauthentik/core/paths/node";
-
 const relativeDirname = dirname(fileURLToPath(import.meta.url));
 
 //#region Base paths
@@ -48,8 +46,6 @@ export const DistDirectory = /** @type {`${WebPackageIdentifier}/${DistDirectory
  * Matches the type defined in the ESBuild context.
  */
 
-const patternflyPath = resolvePackage("@patternfly/patternfly", import.meta);
-
 /**
  * Entry points available for building.
  *

web/scripts/build-web.mjs

@@ -19,7 +19,7 @@ import { ConsoleLogger } from "#logger/node";
 import { DistDirectory, EntryPoint, PackageRoot } from "#paths/node";
 
 import { NodeEnvironment } from "@goauthentik/core/environment/node";
-import { MonoRepoRoot, resolvePackage } from "@goauthentik/core/paths/node";
+import { MonoRepoRoot } from "@goauthentik/core/paths/node";
 import { BuildIdentifier } from "@goauthentik/core/version/node";
 
 import { deepmerge } from "deepmerge-ts";
@@ -37,8 +37,6 @@ const publicBundledDefinitions = Object.fromEntries(
 );
 logger.info(publicBundledDefinitions, "Bundle definitions");
 
-const patternflyPath = resolvePackage("@patternfly/patternfly", import.meta);
-
 /**
  * @type {Readonly<BuildOptions>}
  */
@@ -53,6 +51,7 @@ const BASE_ESBUILD_OPTIONS = {
     minify: NodeEnvironment === "production",
     legalComments: "external",
     splitting: true,
+    color: !process.env.NO_COLOR,
     treeShaking: true,
     tsconfig: path.resolve(PackageRoot, "tsconfig.build.json"),
     loader: {
@@ -80,7 +79,6 @@ const BASE_ESBUILD_OPTIONS = {
                 },
             ],
         }),
-        styleLoaderPlugin(),
         mdxPlugin({
             root: MonoRepoRoot,
         }),
@@ -140,9 +138,11 @@ function doHelp() {
     process.exit(0);
 }
 
+/**
+ *
+ * @returns {Promise<() => Promise<void>>} dispose
+ */
 async function doWatch() {
-    const { promise, resolve, reject } = Promise.withResolvers();
-
     logger.info(`🤖 Watching entry points:\n\t${Object.keys(EntryPoint).join("\n\t")}`);
 
     const entryPoints = Object.values(EntryPoint);
@@ -158,7 +158,7 @@ async function doWatch() {
 
     const buildOptions = createESBuildOptions({
         entryPoints,
-        plugins: developmentPlugins,
+        plugins: [...developmentPlugins, styleLoaderPlugin({ logger, watch: true })],
     });
 
     const buildContext = await esbuild.context(buildOptions);
@@ -176,34 +176,23 @@ async function doWatch() {
     logger.info(`🔓 ${httpURL.href}`);
     logger.info(`🔒 ${httpsURL.href}`);
 
-    let disposing = false;
-
-    const delegateShutdown = () => {
+    return () => {
         logger.flush();
-        console.log("");
+        console.info("");
+        console.info("🛑 Stopping file watcher...");
 
-        // We prevent multiple attempts to dispose the context
-        // because ESBuild will repeatedly restart its internal clean-up logic.
-        // However, sending a second SIGINT will still exit the process immediately.
-        if (disposing) return;
-
-        disposing = true;
-
-        return buildContext.dispose().then(resolve).catch(reject);
+        return buildContext.dispose();
     };
-
-    process.on("SIGINT", delegateShutdown);
-
-    return promise;
 }
 
 async function doBuild() {
-    logger.info(`🤖 Watching entry points:\n\t${Object.keys(EntryPoint).join("\n\t")}`);
+    logger.info(`🤖 Building entry points:\n\t${Object.keys(EntryPoint).join("\n\t")}`);
 
     const entryPoints = Object.values(EntryPoint);
 
     const buildOptions = createESBuildOptions({
         entryPoints,
+        plugins: [styleLoaderPlugin({ logger })],
     });
 
     await esbuild.build(buildOptions);
@@ -245,10 +234,43 @@ await cleanDistDirectory()
     // ---
     .then(() =>
         delegateCommand()
-            .then(() => {
-                process.exit(0);
+            .then((dispose) => {
+                if (!dispose) {
+                    process.exit(0);
+                }
+
+                /**
+                 * @type {Promise<void>}
+                 */
+                const signalListener = new Promise((resolve) => {
+                    // We prevent multiple attempts to dispose the context
+                    // because ESBuild will repeatedly restart its internal clean-up logic.
+                    // However, sending a second SIGINT will still exit the process immediately.
+                    let signalCount = 0;
+
+                    process.on("SIGINT", () => {
+                        if (signalCount > 3) {
+                            // Something is taking too long and the user wants to exit now.
+                            console.log("🛑 Forcing exit...");
+                            process.exit(0);
+                        }
+                    });
+
+                    process.once("SIGINT", () => {
+                        signalCount++;
+
+                        dispose().finally(() => {
+                            console.log("✅ Done!");
+
+                            resolve();
+                        });
+                    });
+
+                    logger.info("🚪 Press Ctrl+C to exit.");
+                });
+
+                return signalListener;
             })
-            .catch(() => {
-                process.exit(1);
-            }),
+            .then(() => process.exit(0))
+            .catch(() => process.exit(1)),
     );