Webpack build process and theme automation improvements

The Drupal theme configuration has undergone recent changes made to the Webpack configuration, SCSS and JavaScript handling, and automation of updates to the orw.libraries.yml file in the custom Drupal theme. These changes are designed to improve the build process, enhance maintainability, and streamline development for other developers working on this theme.

Overview of changes

1. Webpack improvements

• Consolidated the Webpack configuration to handle SCSS and JS files correctly
• Introduced content hashing to ensure proper cache busting
• Prevented unnecessary `.js` files from being generated for SCSS-only entries
• Integrated source maps to aid in debugging during development

2. File handling enhancements

• Automated copying of static CSS and JS assets (e.g., `nsw-core.css`, `nsw-main.css`, and `nsw-main.js`) to the correct output directories
• Enabled dynamic filename updates in orw.libraries.yml to handle content hashes automatically.

3. Automation script

• Created a Node.js script (`update-orw-libraries.js`) to dynamically insert the correct hashed filenames for CSS and JS assets into orw.libraries.yml
• This script ensures that developers no longer need to manually update the YAML file after each build.

Detailed breakdown of changes

Webpack configuration

Updated entry points

The entry points were modified to define SCSS and JS files explicitly. Each SCSS file (e.g., `style.scss`, `switcher.scss`) is set to generate only CSS output. We added `dependOn` options to avoid unnecessary `.js` files.

entry: {
 custom: './assets/src/js/custom.js',  // Generates custom.[hash].js
 style: {
   import: './assets/src/scss/style.scss',
   dependOn: 'custom',
 },
 switcher: {
   import: './assets/src/scss/switcher.scss',
   dependOn: 'custom',
 },
},

The output directory is configured to place compiled CSS and JS files under assets/dist with content hashes for cache busting:

output: {
 filename: 'js/[name].[contenthash].js',
 path: path.resolve('assets/dist'),
 clean: true,
},

Plugins

We use the following plugins for additional build steps:

• MiniCssExtractPlugin to extract CSS files and generate hashed filenames
• CopyWebpackPlugin to copy static files (e.g., `nsw-core.css`, `nsw-main.css`, and `nsw-main.js`) to the appropriate output directories without modifications.

new MiniCssExtractPlugin({
 filename: 'css/[name].[contenthash].css',
}),
new CopyWebpackPlugin({
 patterns: [
   {
     from: 'scss/nsw-*.css*',
     to: 'css/[name][ext]',
     context: path.resolve('assets/src'),
   },
   {
     from: 'js/nsw-main.js*',
     to: 'js/[name][ext]',
     context: path.resolve('assets/src'),
   },
 ],
}),

Script automation for YAML updates

The Node.js script `update-orw-libraries.js` automates the process of updating the orw.libraries.yml file with the latest hashed CSS and JS files generated during the Webpack build.

How it works

1. The script reads the files in assets/dist to locate the appropriate files:

• CSS: `style.[hash].css`, `switcher.[hash].css`
• JS: `custom.[hash].js`
• Static assets like `nsw-core.css` and `nsw-main.js`.

2. The script updates the YAML structure dynamically:

libraries['global-styling'].css.theme = {
 [`assets/dist/css/style.${styleHash}.css`]: {},
 [`assets/dist/css/switcher.${switcherHash}.css`]: {},
};
libraries['global-styling'].js = {
 [`assets/dist/js/custom.${customHash}.js`]: {},
};

3. It saves the updated YAML, ensuring that the latest assets are used by Drupal without manual intervention.

Example output in orw.libraries.yml

Before the script is executed, placeholders are present in the YAML file:

global-styling:
 version: 1.x
 css:
   theme:
     assets/dist/css/style.[contenthash].css: {}
     assets/dist/css/switcher.[contenthash].css: {}
 js:
   assets/dist/js/custom.[contenthash].js: {}

After execution, the actual filenames are injected based on the current build:

global-styling:
 version: 1.x
 css:
   theme:
     assets/dist/css/style.123abc456def.css: {}
     assets/dist/css/switcher.789ghi012jkl.css: {}
 js:
   assets/dist/js/custom.mnopqrs987tuv.js: {}

Improvements to workflow

• Automated cache busting: With content hashes in filenames, browsers always fetch the latest assets after a build, reducing cache issues
• Simplified YAML updates: Developers no longer need to manually edit orw.libraries.yml after each build
• Reduced manual errors: The script ensures consistency and prevents duplicated or incorrect filenames (e.g., `style.style.[hash].css`).

How to use the new process

1. Run the build process:

npm run build-all

This command performs the following tasks:

• Builds the CSS and JS files via Webpack
• Updates the orw.libraries.yml file with the correct hashed filenames.

2. Commit the updated files:

• Ensure the generated files under assets/dist and the updated orw.libraries.yml are committed to the repository.

Summary

These changes enhance the development workflow by automating tasks, improving performance, and reducing the risk of errors. When using these changes follow the updated process to ensure consistent builds and deployments for the ORW theme.