theme-elementary

Asset Building Process

This document explains how the theme’s asset pipeline builds and manages CSS, JavaScript, and Interactivity API modules, and how to add a new file to it.

You make your edits under src/; the build process compiles them into the gitignored assets/build/ directory, which you should never edit directly — anything written there is overwritten on the next build. Local development owns the actual watch/build commands. The pipeline itself is Webpack, configured in webpack.config.js, with its build scripts and dependencies living in package.json.

Overview

Our asset pipeline is managed by Webpack. The build process involves the following steps:

CSS/SCSS files under src/css/frontend/, src/css/admin/, and src/css/editor/ are extracted with MiniCssExtractPlugin into their matching directories under assets/build/css/, and minified with CssMinimizerPlugin in production builds.
JavaScript files under the matching src/js/ context directories are bundled and processed through Babel for browser compatibility, then output to assets/build/js/. webpack-remove-empty-scripts removes any script entry that has no content, so a directory with only CSS doesn’t emit an empty .js file.
Modules under src/js/frontend/modules/ are handled separately, through a dedicated moduleScripts entry in webpack.config.js, and compiled into assets/build/js/modules/ to ensure they’re loaded correctly.
Fonts are copied from src/fonts/ to assets/build/fonts/.
SVGs are optimized with SVGO and copied from src/images/svg/ to assets/build/images/svg/; an SVG that fails to optimize is copied unchanged rather than failing the build.

frontend/, admin/, and editor/ are the three contexts under both src/css/ and src/js/, for public-facing, wp-admin, and block-editor code respectively. Frontend and admin scripts share one build; editor scripts build separately so they keep webpack-dev-server’s Fast Refresh during development.

Key Configuration Files

webpack.config.js: This is the main configuration file for building assets.
package.json: Contains the scripts and dependencies necessary for the build process.

Directory Structure

src/css/{frontend,admin,editor}: Contains CSS/SCSS files, organized by context.
src/js/{frontend,admin,editor}: Contains JavaScript files, organized by context.
src/js/frontend/modules: Contains Interactivity API module scripts.
src/components: Contains component assets, built into assets/build/js/components/ and assets/build/css/components/.
src/fonts: Font files copied to assets/build/fonts/ during build via CopyWebpackPlugin.
src/images/svg: Source SVGs optimized by SVGO and copied to assets/build/images/svg/ during build via CopyWebpackPlugin.
assets/build/js: Where built JavaScript files are output.
assets/build/css: Where built CSS files are output.

Adding New Scripts or Modules

To add a new script or module to the build process, follow these steps:

Adding a New Script

Place your JavaScript file in the appropriate context subdirectory under src/js/. Example: src/js/frontend/my-script.js.
The readAllFileEntries helper in webpack.config.js automatically discovers files in src/js/frontend/, src/js/admin/, and src/js/editor/. No webpack config changes are needed.

Run the build script:

npm run build:dev  # For development
npm run build:prod # For production

Register and enqueue it through the theme’s inc/Core/Assets.php on the appropriate hook, following the existing asset registrations. Discovery adds a file to the build; it does not automatically enqueue every new entry in WordPress. The framework’s asset-loader reference explains its methods.

Adding a New Module

Place your module JavaScript file in the src/js/frontend/modules directory. Example: src/js/frontend/modules/my-module.js.
The modules will automatically be included in the Webpack build process via the readAllFileEntries helper:
```
entry: () => readAllFileEntries( './src/js/frontend/modules' ),
```
Run the build script:
```
npm run build:dev  # For development
npm run build:prod # For production
```
Do not put ordinary scripts inside the modules directory — it’s reserved for Interactivity API modules.

Avoid Bundling Specific Files

For example, if you have a file like _my-excluded-script.js or _my-excluded-styles.css, Webpack will ignore it when bundling and it won’t be included in the final output.

How to Exclude Files

CSS/SCSS: If you want to add a CSS file without bundling it, name it starting with an underscore. Example: _my-excluded-styles.scss.
JavaScript: Similarly, prefix JS files with an underscore to prevent bundling. Example: _my-excluded-script.js.

By naming files with the underscore, we make sure they are excluded from the Webpack build process but can still be used elsewhere in the project — for imported partials that other files pull in, such as _variables.scss or a shared _helpers.js.

Components and blocks

A component’s asset filename matches its directory, for example src/components/card/card.js and card.scss. Its PHP render file stays in src/components/card/card.php. The theme component loader connects rendering and assets; see Included features.

Custom blocks have their own build and registration. Keep their metadata and sources under src/blocks/, and point PHP registration at the corresponding assets/build/blocks/ output. The starter does not require a custom block to render its standard block-theme templates.

Styles and Tailwind

SCSS globals/mixins and shared imports live under src/css/. Optional Tailwind uses its own entry and generates WordPress preset tokens at build time; see Tailwind. Webpack is already configured for these theme inputs.

This site is open source. Improve this page.