Modern Webpack Setup

Chisel ships with a modern, production‑grade Webpack pipeline (via chisel-scripts) that powers fast local development and optimized builds. You get instant feedback with HMR, first‑class ESNext support (Babel), modular SCSS with PostCSS, and automatic asset handling for images, fonts, and SVGs. The setup performs tree‑shaking, code‑splitting, hashed filenames, and source maps, outputting clean bundles into build/ for scripts, styles, and blocks. Environment‑aware commands (npm run start / npm run build) ensure you develop quickly and deploy lean, while theme integration hooks in inc/WP/Assets.php register and enqueue the right assets only where needed.

Overview

Baseline toolchain: @wordpress/scripts (Webpack/Babel/PostCSS) adjusted by chisel-scripts.
Sources: src/ (scripts, styles, blocks).
Outputs: build/ (compiled assets).
Static assets: assets/ (fonts, icons, example assets; hashing helper present).
Quality gates: ESLint, Stylelint, Prettier, PHPCS, TwigCS wired via npm scripts.

Source structure

All source files are under src/:

Scripts: src/scripts/
- Top-level files (entry-like):
  - app.js — initializes core frontend modules (./modules/*) File: src/scripts/app.js
  - editor.js — editor-side imports (./editor/*) File: src/scripts/editor.js
  - admin.js — admin-side (ACF integration) File: src/scripts/admin.js
  - login.js — WP login screen customization File: src/scripts/login.js
- Structure:
  - admin/, editor/, modules/ subfolders for organization.
Styles: src/styles/
- Top-level SCSS (commonly used as entries):
  - main.scss — main theme stylesheet (Sass modules via @use) File: src/styles/main.scss
  - editor.scss — block editor styles
  - admin.scss — wp-admin styles
  - login.scss — login screen styles
  - gravity-forms.scss — Gravity Forms integration styles
  - woocommerce.scss — WooCommerce styles
- Structure:
  - blocks/, components/, elements/, generic, objects/, widgets/, utilities/, vendor, woo/, wp-admin, wp-editor.
Blocks:
- src/blocks/ — native Gutenberg blocks
- src/blocks-acf/ — ACF-based blocks
Design tokens/partials:
- src/design/ — central place for variables, mixins, and shared Sass modules

Outputs and assets

Build directory: build**/**
Static assets: assets**/** – contains fonts, icon, example block assets, and hashing utilities for cache‑busting.

Note: The theme integrates asset hashing to produce cache‑safe filenames. The PHP helpers in assets/ are used by the theme to resolve hashed names when enqueuing.

What the pipeline provides

Transpilation of modern JS via @wordpress/scripts ****(Babel) and PostCSS.
Sass (SCSS) compilation from src/styles/ with modular @use/@forward structure.
Production optimizations (minification, tree‑shaking where applicable).
Logical separation of bundles for frontend/editor/blocks inferred from src/.
Watch/dev mode with fast feedback via chisel-scripts start / npm run start .

Quality gates / Configuration files

webpack.config.js — entry point to the adjusted Webpack config.
JavaScript linting: .eslintrc.cjs and eslint scripts.
Styles linting: stylelint.config.mjs.
Code style: prettier.config.mjs.
PHP coding standards: phpcs.xml.
Twig coding standards: twig_cs.php and .twig-cs-fixer.php.

All of these are run as a part of the build process (npm run build).

Development workflow

Edit files in src/ (scripts/styles/blocks).
Run npm run dev to compile in watch mode.
Commit only source and built assets according to your repo policy.
For releases, run npm run build to produce minified, hashed assets in build/.
Fix any issues reported by the linters and and repeat #4.