Refactor build pipeline for performance and dev output reliability

Replace JS/CSS minifiers with esbuild to reduce build times while
preserving outputs.

Enable `thread-loader` by default in dev and production. Choose workers
dynamically (based on CPU cores) and allow overrides via environment
variables. Keep filesystem cache enabled and make cache compression
configurable, defaulting to uncompressed for faster warm builds on
CPU-bound machines. Add BUILD_PARALLEL toggle (default on) to switch
between parallel and sequential production variant builds. Ensure
watch-once dev builds exit cleanly.

Adopt `sass-embedded` for SASS processing. In development, use
`style-loader` to speed up CSS/SCSS compilation while keeping production
outputs unchanged. Maintain CSP-safe source maps for extension contexts
and suppress CSS 404 noise in development outputs.

Additionally, dependency caching has been added to the GitHub Actions
workflow to accelerate CI/CD runs.

Results on this DO VPS (2 cores, ~4 GiB RAM):
- Production first run (cold): ~44s (baseline ~105s)
- Production second run (warm): ~19s (baseline ~39s)
- Development first run: ~31s; second run: ~29s

Times vary by environment; numbers above are for this machine.

Author: PeterDaveHello

.github/copilot-instructions.md

@@ -17,6 +17,22 @@ Always reference these instructions first and fall back to search or bash comman
 - Lint code: `npm run lint` -- uses ESLint.
 - Safari build: `npm run build:safari` (see Platform-Specific Instructions for details)
 
+### Build Performance Options
+
+- BUILD_PARALLEL: Toggle parallel build of production variants
+  - Default: on (parallel). Set to `0` to run sequentially (lower CPU/IO spikes on low-core machines)
+- BUILD_THREAD / BUILD_THREAD_WORKERS: Control Babel parallelism via thread-loader
+  - Default: threads enabled in dev/prod; workers = CPU cores
+  - Set `BUILD_THREAD=0` to disable; set `BUILD_THREAD_WORKERS=<n>` to override worker count
+- BUILD_CACHE_COMPRESSION: Webpack filesystem cache compression
+  - Default: `0` (no compression) for faster warm builds on CPU‑bound SSD machines
+  - Options: `0|false|none`, `gzip` (or `brotli` if explicitly desired)
+  - Affects only `.cache/webpack` size/speed; does not change final artifacts
+- BUILD_WATCH_ONCE (dev): When set, `npm run dev` runs a single build and exits (useful for timing)
+
+Performance defaults: esbuild is used for JS/CSS minification; dev injects CSS via style-loader,
+prod extracts CSS via MiniCssExtractPlugin; thread-loader is enabled by default in both dev and prod.
+
 ### Build Output Structure
 
 Production build creates multiple variants in `build/` directory:

.github/workflows/pre-release-build.yml

@@ -24,7 +24,23 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 20
+      - name: Cache npm cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-node-
       - run: npm ci
+      - name: Cache Webpack filesystem cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            .cache/webpack
+            node_modules/.cache/webpack
+          key: ${{ runner.os }}-webpack-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-webpack-
       - run: npm run build
 
       - uses: josStorer/get-current-time@v2

build.mjs

@@ -2,23 +2,42 @@ import archiver from 'archiver'
 import fs from 'fs-extra'
 import path from 'path'
 import webpack from 'webpack'
+import os from 'os'
 import ProgressBarPlugin from 'progress-bar-webpack-plugin'
 import CssMinimizerPlugin from 'css-minimizer-webpack-plugin'
 import MiniCssExtractPlugin from 'mini-css-extract-plugin'
-import TerserPlugin from 'terser-webpack-plugin'
+import { EsbuildPlugin } from 'esbuild-loader'
 import { BundleAnalyzerPlugin } from 'webpack-bundle-analyzer'
 
 const outdir = 'build'
 
 const __dirname = path.resolve()
 const isProduction = process.argv[2] !== '--development' // --production and --analyze are both production
 const isAnalyzing = process.argv[2] === '--analyze'
+const parallelBuild = process.env.BUILD_PARALLEL === '0' ? false : true
+const isWatchOnce = !!process.env.BUILD_WATCH_ONCE
+// Cache compression control: default none; allow override via env
+const cacheCompressionEnv = process.env.BUILD_CACHE_COMPRESSION
+let cacheCompressionOption
+if (cacheCompressionEnv) {
+  const v = String(cacheCompressionEnv).toLowerCase()
+  if (v === '0' || v === 'false' || v === 'none') cacheCompressionOption = false
+  else if (v === 'brotli') cacheCompressionOption = 'brotli'
+  else cacheCompressionOption = 'gzip' // treat any truthy/unknown as gzip
+}
+const cpuCount = os.cpus()?.length || 1
+const envWorkers = process.env.BUILD_THREAD_WORKERS
+  ? parseInt(process.env.BUILD_THREAD_WORKERS, 10)
+  : undefined
+const threadWorkers = Number.isInteger(envWorkers) && envWorkers > 0 ? envWorkers : cpuCount
+// Enable threads by default; allow disabling via BUILD_THREAD=0
+const enableThread = process.env.BUILD_THREAD === '0' ? false : true
 
 async function deleteOldDir() {
   await fs.rm(outdir, { recursive: true, force: true })
 }
 
-async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, callback) {
+async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuildDir, callback) {
   const shared = [
     'preact',
     'webextension-polyfill',
@@ -33,6 +52,8 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, callback)
   ]
   if (isWithoutKatex) shared.push('./src/components')
 
+  const sassImpl = await import('sass-embedded')
+
   const compiler = webpack({
     entry: {
       'content-script': {
@@ -54,18 +75,29 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, callback)
     },
     output: {
       filename: '[name].js',
-      path: path.resolve(__dirname, outdir),
+      path: path.resolve(__dirname, sourceBuildDir || outdir),
     },
     mode: isProduction ? 'production' : 'development',
-    devtool: isProduction ? false : 'inline-source-map',
+    devtool: isProduction ? false : 'cheap-module-source-map',
+    cache: {
+      type: 'filesystem',
+      // default none; override via BUILD_CACHE_COMPRESSION=gzip|brotli
+      compression: cacheCompressionOption ?? false,
+      buildDependencies: {
+        config: [path.resolve('build.mjs')],
+      },
+    },
     optimization: {
       minimizer: [
-        new TerserPlugin({
-          terserOptions: {
-            output: { ascii_only: true },
-          },
+        // Use esbuild for JS minification (faster than Terser)
+        new EsbuildPlugin({
+          target: 'es2017',
+          legalComments: 'none',
+        }),
+        // Use esbuild-based CSS minify via css-minimizer plugin
+        new CssMinimizerPlugin({
+          minify: CssMinimizerPlugin.esbuildMinify,
         }),
-        new CssMinimizerPlugin(),
       ],
       concatenateModules: !isAnalyzing,
     },
@@ -103,6 +135,7 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, callback)
     ],
     resolve: {
       extensions: ['.jsx', '.mjs', '.js'],
+      symlinks: false,
       alias: {
         parse5: path.resolve(__dirname, 'node_modules/parse5'),
         ...(minimal
@@ -124,9 +157,23 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, callback)
             fullySpecified: false,
           },
           use: [
+            ...(enableThread
+              ? [
+                  {
+                    loader: 'thread-loader',
+                    options: {
+                      workers: threadWorkers,
+                      // Ensure one-off dev build exits quickly
+                      poolTimeout: isProduction ? 2000 : isWatchOnce ? 0 : Infinity,
+                    },
+                  },
+                ]
+              : []),
             {
               loader: 'babel-loader',
               options: {
+                cacheDirectory: true,
+                cacheCompression: false,
                 presets: [
                   '@babel/preset-env',
                   {
@@ -149,7 +196,7 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, callback)
         {
           test: /\.s[ac]ss$/,
           use: [
-            MiniCssExtractPlugin.loader,
+            isProduction ? MiniCssExtractPlugin.loader : 'style-loader',
             {
               loader: 'css-loader',
               options: {
@@ -158,13 +205,14 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, callback)
             },
             {
               loader: 'sass-loader',
+              options: { implementation: sassImpl },
             },
           ],
         },
         {
           test: /\.less$/,
           use: [
-            MiniCssExtractPlugin.loader,
+            isProduction ? MiniCssExtractPlugin.loader : 'style-loader',
             {
               loader: 'css-loader',
               options: {
@@ -179,7 +227,7 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, callback)
         {
           test: /\.css$/,
           use: [
-            MiniCssExtractPlugin.loader,
+            isProduction ? MiniCssExtractPlugin.loader : 'style-loader',
             {
               loader: 'css-loader',
             },
@@ -258,7 +306,12 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, callback)
     },
   })
   if (isProduction) compiler.run(callback)
-  else compiler.watch({}, callback)
+  else {
+    const watching = compiler.watch({}, (err, stats) => {
+      callback(err, stats)
+      if (process.env.BUILD_WATCH_ONCE) watching.close(() => {})
+    })
+  }
 }
 
 async function zipFolder(dir) {
@@ -275,28 +328,30 @@ async function copyFiles(entryPoints, targetDir) {
   if (!fs.existsSync(targetDir)) await fs.mkdir(targetDir)
   await Promise.all(
     entryPoints.map(async (entryPoint) => {
-      await fs.copy(entryPoint.src, `${targetDir}/${entryPoint.dst}`)
+      if (await fs.pathExists(entryPoint.src)) {
+        await fs.copy(entryPoint.src, `${targetDir}/${entryPoint.dst}`)
+      }
     }),
   )
 }
 
-async function finishOutput(outputDirSuffix) {
+async function finishOutput(outputDirSuffix, sourceBuildDir = outdir) {
   const commonFiles = [
     { src: 'src/logo.png', dst: 'logo.png' },
     { src: 'src/rules.json', dst: 'rules.json' },
 
-    { src: 'build/shared.js', dst: 'shared.js' },
-    { src: 'build/content-script.css', dst: 'content-script.css' }, // shared
+    { src: `${sourceBuildDir}/shared.js`, dst: 'shared.js' },
+    { src: `${sourceBuildDir}/content-script.css`, dst: 'content-script.css' }, // shared
 
-    { src: 'build/content-script.js', dst: 'content-script.js' },
+    { src: `${sourceBuildDir}/content-script.js`, dst: 'content-script.js' },
 
-    { src: 'build/background.js', dst: 'background.js' },
+    { src: `${sourceBuildDir}/background.js`, dst: 'background.js' },
 
-    { src: 'build/popup.js', dst: 'popup.js' },
-    { src: 'build/popup.css', dst: 'popup.css' },
+    { src: `${sourceBuildDir}/popup.js`, dst: 'popup.js' },
+    { src: `${sourceBuildDir}/popup.css`, dst: 'popup.css' },
     { src: 'src/popup/index.html', dst: 'popup.html' },
 
-    { src: 'build/IndependentPanel.js', dst: 'IndependentPanel.js' },
+    { src: `${sourceBuildDir}/IndependentPanel.js`, dst: 'IndependentPanel.js' },
     { src: 'src/pages/IndependentPanel/index.html', dst: 'IndependentPanel.html' },
   ]
 
@@ -306,6 +361,18 @@ async function finishOutput(outputDirSuffix) {
     [...commonFiles, { src: 'src/manifest.json', dst: 'manifest.json' }],
     chromiumOutputDir,
   )
+  // In development, ensure placeholder CSS files exist to avoid 404 noise
+  if (!isProduction) {
+    const chromiumCssPlaceholders = [
+      path.join(chromiumOutputDir, 'popup.css'),
+      path.join(chromiumOutputDir, 'content-script.css'),
+    ]
+    for (const p of chromiumCssPlaceholders) {
+      if (!(await fs.pathExists(p))) {
+        await fs.outputFile(p, '/* dev placeholder */\n')
+      }
+    }
+  }
   if (isProduction) await zipFolder(chromiumOutputDir)
 
   // firefox
@@ -314,43 +381,92 @@ async function finishOutput(outputDirSuffix) {
     [...commonFiles, { src: 'src/manifest.v2.json', dst: 'manifest.json' }],
     firefoxOutputDir,
   )
-  if (isProduction) await zipFolder(firefoxOutputDir)
-}
-
-function generateWebpackCallback(finishOutputFunc) {
-  return async function webpackCallback(err, stats) {
-    if (err || stats.hasErrors()) {
-      console.error(err || stats.toString())
-      return
+  // In development, ensure placeholder CSS files exist to avoid 404 noise
+  if (!isProduction) {
+    const firefoxCssPlaceholders = [
+      path.join(firefoxOutputDir, 'popup.css'),
+      path.join(firefoxOutputDir, 'content-script.css'),
+    ]
+    for (const p of firefoxCssPlaceholders) {
+      if (!(await fs.pathExists(p))) {
+        await fs.outputFile(p, '/* dev placeholder */\n')
+      }
     }
-    // console.log(stats.toString())
-
-    await finishOutputFunc()
   }
+  if (isProduction) await zipFolder(firefoxOutputDir)
 }
 
 async function build() {
   await deleteOldDir()
   if (isProduction && !isAnalyzing) {
-    // await runWebpack(
-    //   true,
-    //   false,
-    //   generateWebpackCallback(() => finishOutput('-without-katex')),
-    // )
-    // await new Promise((r) => setTimeout(r, 5000))
-    await runWebpack(
-      true,
-      true,
-      true,
-      generateWebpackCallback(() => finishOutput('-without-katex-and-tiktoken')),
-    )
-    await new Promise((r) => setTimeout(r, 10000))
+    const tmpFull = `${outdir}/.tmp-full`
+    const tmpMin = `${outdir}/.tmp-min`
+    if (parallelBuild) {
+      await Promise.all([
+        new Promise((resolve, reject) =>
+          runWebpack(true, true, true, tmpMin, async (err, stats) => {
+            if (err || stats.hasErrors()) {
+              console.error(err || stats.toString())
+              reject(err || new Error('webpack error'))
+              return
+            }
+            await finishOutput('-without-katex-and-tiktoken', tmpMin)
+            resolve()
+          }),
+        ),
+        new Promise((resolve, reject) =>
+          runWebpack(false, false, false, tmpFull, async (err, stats) => {
+            if (err || stats.hasErrors()) {
+              console.error(err || stats.toString())
+              reject(err || new Error('webpack error'))
+              return
+            }
+            await finishOutput('', tmpFull)
+            resolve()
+          }),
+        ),
+      ])
+      await fs.rm(tmpFull, { recursive: true, force: true })
+      await fs.rm(tmpMin, { recursive: true, force: true })
+    } else {
+      await new Promise((resolve, reject) =>
+        runWebpack(true, true, true, tmpMin, async (err, stats) => {
+          if (err || stats.hasErrors()) {
+            console.error(err || stats.toString())
+            reject(err || new Error('webpack error'))
+            return
+          }
+          await finishOutput('-without-katex-and-tiktoken', tmpMin)
+          resolve()
+        }),
+      )
+      await new Promise((resolve, reject) =>
+        runWebpack(false, false, false, tmpFull, async (err, stats) => {
+          if (err || stats.hasErrors()) {
+            console.error(err || stats.toString())
+            reject(err || new Error('webpack error'))
+            return
+          }
+          await finishOutput('', tmpFull)
+          resolve()
+        }),
+      )
+      await fs.rm(tmpFull, { recursive: true, force: true })
+      await fs.rm(tmpMin, { recursive: true, force: true })
+    }
+    return
   }
-  await runWebpack(
-    false,
-    false,
-    false,
-    generateWebpackCallback(() => finishOutput('')),
+
+  await new Promise((resolve, reject) =>
+    runWebpack(false, false, false, outdir, async (err, stats) => {
+      if (err || stats.hasErrors()) {
+        console.error(err || stats.toString())
+        reject(err || new Error('webpack error'))
+        return
+      }
+      await finishOutput('')
+      resolve()
+    }),
   )
 }