Consolidate Grunt + Webpack into a single build pipeline

[jjroelofs]

What is the DXPR engineering productivity problem to solve?

The theme currently uses two separate build systems running in parallel:

1. Grunt — orchestrates SCSS compilation (grunt-sass), CSS post-processing (autoprefixer, postcss-pxtorem), and JS minification (terser)
2. Webpack — handles JS bundling and Babel transpilation

This dual-system architecture creates several productivity problems:

• Higher onboarding friction: New contributors must understand two build tools, two config files (Gruntfile.js + webpack.config.js), and how they interact
• Maintenance burden: Two sets of plugins to keep updated, two places where build configuration can diverge
• No tree-shaking: Grunt+Terser pipeline doesn't support tree-shaking, meaning unused code ships to production
• Inconsistent source maps: Two tools generating source maps independently can lead to debugging difficulties
• Docker build complexity: The docker-compose.yml dev service must coordinate both tools

Problem identification checklist

• The root cause of the problem is identified.
• The surface of the problem is as small as possible.

What are the potential solutions?

Solution A: Consolidate into Webpack only

• Pros: Already partially in use, mature ecosystem, handles SCSS (sass-loader), JS (babel-loader), and minification (terser-webpack-plugin) in one pipeline. Supports tree-shaking, code splitting, and proper source maps.
• Cons: Webpack config can be verbose. Slightly slower cold builds than Vite.
• Weight: Medium effort — migrate Grunt SCSS tasks to webpack sass-loader, remove Gruntfile.js

Solution B: Migrate to Vite

• Pros: Faster dev builds (ESBuild), simpler config, modern defaults, excellent SCSS support, tree-shaking
• Cons: Newer tool with less Drupal ecosystem precedent. May require adjusting output format for Drupal library compatibility.
• Weight: Medium-high effort — new tool, need to verify Drupal asset compatibility

Solution C: Keep Grunt, remove Webpack

• Pros: Minimal change to existing SCSS workflow

• Cons: Grunt is effectively unmaintained. Loses JS bundling, tree-shaking, and modern build features.

• Weight: Low effort but moves in the wrong direction

• All potential solutions are listed.

• A solution has been chosen for the first iteration: TBD — recommend Solution A (Webpack consolidation) as the pragmatic choice

Verify that the solution has improved the situation

• The solution improved the situation.
  • Build runs as a single command with a single config file
  • Contributors only need to understand one build tool
  • package.json has fewer dev dependencies
  • Build output size is equal or smaller (tree-shaking)