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/, andsrc/css/editor/are extracted withMiniCssExtractPlugininto their matching directories underassets/build/css/, and minified withCssMinimizerPluginin production builds. - JavaScript files under the matching
src/js/context directories are bundled and processed through Babel for browser compatibility, then output toassets/build/js/.webpack-remove-empty-scriptsremoves any script entry that has no content, so a directory with only CSS doesn't emit an empty.jsfile. - Modules under
src/js/frontend/modules/are handled separately, through a dedicatedmoduleScriptsentry inwebpack.config.js, and compiled intoassets/build/js/modules/to ensure they're loaded correctly. - Fonts are copied from
src/fonts/toassets/build/fonts/. - SVGs are optimized with SVGO and copied from
src/images/svg/toassets/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/andassets/build/css/components/. - src/fonts: Font files copied to
assets/build/fonts/during build viaCopyWebpackPlugin. - src/images/svg: Source SVGs optimized by SVGO and copied to
assets/build/images/svg/during build viaCopyWebpackPlugin. - 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
readAllFileEntrieshelper inwebpack.config.jsautomatically discovers files insrc/js/frontend/,src/js/admin/, andsrc/js/editor/. No webpack config changes are needed. -
Run the build script:
npm run build:dev # For developmentnpm run build:prod # For production -
Register and enqueue it through the theme's
inc/Core/Assets.phpon 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/modulesdirectory. Example:src/js/frontend/modules/my-module.js. -
The modules will automatically be included in the Webpack build process via the
readAllFileEntrieshelper:entry: () => readAllFileEntries( './src/js/frontend/modules' ), -
Run the build script:
npm run build:dev # For developmentnpm run build:prod # For productionDo not put ordinary scripts inside the
modulesdirectory — 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.