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 Hot Module Replacement, first-class ESNext support via 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 dev / npm run build) ensure you develop quickly and deploy lean, while theme integration hooks in core/WP/Assets.php register and enqueue the right assets only where needed.

Overview

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

Webpack Configuration

The webpack.config.js extends the default @wordpress/scripts configuration with Chisel-specific adjustments:

const defaultConfig = require('@wordpress/scripts/config/webpack.config');
const { adjustWebpackConfig } = require('chisel-scripts');

const updatedConfig = adjustWebpackConfig(defaultConfig, __dirname);

module.exports = updatedConfig;

const defaultConfig = require('@wordpress/scripts/config/webpack.config');
const { adjustWebpackConfig } = require('chisel-scripts');

const updatedConfig = adjustWebpackConfig(defaultConfig, __dirname);

module.exports = updatedConfig;

JavaScript

This approach ensures compatibility with WordPress core tooling while adding Chisel enhancements like:

Multiple entry points for different contexts (frontend, admin, editor, login)
Automatic block discovery and compilation
SCSS design token integration
Fast refresh mode for development

Source structure

All source files are under src/:

src/
├── scripts/          # JavaScript modules
├── styles/           # SCSS stylesheets
├── blocks/           # Native WordPress blocks
├── blocks-acf/       # ACF-based blocks
└── design/           # Shared SCSS tokens and mixins

src/
├── scripts/          # JavaScript modules
├── styles/           # SCSS stylesheets
├── blocks/           # Native WordPress blocks
├── blocks-acf/       # ACF-based blocks
└── design/           # Shared SCSS tokens and mixins

Scripts (`src/scripts/`)

Entry points:

File	Purpose
`app.js`	Frontend entry — initializes modules from `./modules/*`
`editor.js`	Block editor — imports from `./editor/*`
`admin.js`	WP Admin — ACF integration and admin scripts
`login.js`	WP Login screen customization

Subfolders:

Folder	Purpose
`modules/`	Frontend modules (load-more, slider, main-nav, utils)
`editor/`	Editor-specific scripts
`admin/`	Admin-specific scripts

Styles (`src/styles/`)

Entry points:

File	Purpose
`main.scss`	Main theme stylesheet
`editor.scss`	Block editor styles
`admin.scss`	WP Admin styles
`login.scss`	Login screen styles
`woocommerce.scss`	WooCommerce integration
`gravity-forms.scss`	Gravity Forms integration

ITCSS Layer Structure:

Layer	Purpose
`generic/`	Resets, normalize, box-sizing
`elements/`	Bare HTML element styles (typography, forms, tables)
`objects/`	Layout patterns (grid, layout, media)
`components/`	BEM components (buttons, cards, navigation)
`blocks/`	Block-specific styles
`widgets/`	Widget styles
`utilities/`	Utility/helper classes
`vendor/`	Third-party styles (Swiper, etc.)
`woo/`	WooCommerce-specific styles
`wp-admin/`	Admin-specific overrides
`wp-editor/`	Editor-specific overrides

Design Tokens (`src/design/`)

Central place for variables, mixins, and shared Sass modules:

src/design/
├── _index.scss       # Main export (forwards tools)
├── settings/         # Variables (colors, typography, spacing)
└── tools/            # Mixins and functions

src/design/
├── _index.scss       # Main export (forwards tools)
├── settings/         # Variables (colors, typography, spacing)
└── tools/            # Mixins and functions

Import design tokens in your stylesheets:

@use '../../design' as *;

@use '../../design' as *;

SCSS

Blocks

Directory	Type	Description
`src/blocks/`	Native	WordPress/React blocks with edit.js, save.js, view.js
`src/blocks-acf/`	ACF	PHP/Twig-rendered blocks with Twig templates

See Native and ACF block support with auto‑registration for detailed documentation.

Outputs and assets

Build directory (`build/`)

Note: The PHP helper in assets/hashes.php is used by the theme to resolve hashed filenames when enqueuing assets, enabling cache-safe deployments.

Compiled assets generated by npm run build:

build/
├── scripts/
│   ├── app.js              # Frontend bundle
│   ├── admin.js            # Admin bundle
│   ├── editor.js           # Editor bundle
│   ├── login.js            # Login bundle
│   └── *.asset.php         # Asset manifests (dependencies, version)
├── styles/
│   ├── main.css            # Main stylesheet
│   ├── admin.css           # Admin styles
│   ├── editor.css          # Editor styles
│   ├── login.css           # Login styles
│   ├── woocommerce.css     # WooCommerce styles
│   ├── gravity-forms.css   # Gravity Forms styles
│   └── *.asset.php         # Style manifests
├── blocks/                 # Compiled native blocks
│   └── accordion/
│       ├── block.json
│       ├── index.js
│       ├── view.js
│       ├── style-index.css
│       └── *.asset.php
├── blocks-acf/             # Compiled ACF blocks
│   └── slider/
│       ├── block.json
│       ├── script.js
│       ├── style-index.css
│       └── *.asset.php
└── runtime.js              # Webpack runtime (present in dev mode)

build/
├── scripts/
│   ├── app.js              # Frontend bundle
│   ├── admin.js            # Admin bundle
│   ├── editor.js           # Editor bundle
│   ├── login.js            # Login bundle
│   └── *.asset.php         # Asset manifests (dependencies, version)
├── styles/
│   ├── main.css            # Main stylesheet
│   ├── admin.css           # Admin styles
│   ├── editor.css          # Editor styles
│   ├── login.css           # Login styles
│   ├── woocommerce.css     # WooCommerce styles
│   ├── gravity-forms.css   # Gravity Forms styles
│   └── *.asset.php         # Style manifests
├── blocks/                 # Compiled native blocks
│   └── accordion/
│       ├── block.json
│       ├── index.js
│       ├── view.js
│       ├── style-index.css
│       └── *.asset.php
├── blocks-acf/             # Compiled ACF blocks
│   └── slider/
│       ├── block.json
│       ├── script.js
│       ├── style-index.css
│       └── *.asset.php
└── runtime.js              # Webpack runtime (present in dev mode)

Static assets (`assets/`)

assets/
├── fonts/           # Webfonts (.woff2)
├── icons/           # Built SVG sprite
├── icons-source/    # SVG source files
├── images/          # Theme images
└── hashes.php       # Build hash map (autogenerated)

assets/
├── fonts/           # Webfonts (.woff2)
├── icons/           # Built SVG sprite
├── icons-source/    # SVG source files
├── images/          # Theme images
└── hashes.php       # Build hash map (autogenerated)

What the pipeline provides

Development mode (`npm run dev`)

Fast refresh: Changes to CSS and JavaScript are applied instantly without full page reload
Source maps: Debug original source files in browser DevTools
Watch mode: Automatic recompilation on file changes
Error overlay: Build errors displayed in the browser

Production mode (`npm run build`)

Transpilation: Modern JavaScript via Babel (@wordpress/scripts)
PostCSS processing: Autoprefixer, CSS optimization
SCSS compilation: Modular @use/@forward structure
Minification: JavaScript and CSS minification
Tree-shaking: Remove unused code
Code splitting: Separate bundles for different contexts
Hashed filenames: Cache-busting for production
Asset manifests: .asset.php files with dependencies and versions

WordPress Interactivity API Support

Chisel includes @wordpress/interactivity as a dependency, enabling the WordPress Interactivity API for building interactive blocks:

{
  "dependencies": {
    "@wordpress/interactivity": "^6.36.0"
  }
}

{
  "dependencies": {
    "@wordpress/interactivity": "^6.36.0"
  }
}

JSON

Use the --experimental-modules flag (enabled by default in Chisel) to enable module support:

{
  "scripts": {
    "start": "chisel-scripts start --experimental-modules",
    "build-scripts": "chisel-scripts build --experimental-modules"
  }
}

{
  "scripts": {
    "start": "chisel-scripts start --experimental-modules",
    "build-scripts": "chisel-scripts build --experimental-modules"
  }
}

JSON

Quality gates / Configuration files

File	Purpose
`webpack.config.js`	Webpack configuration entry point
`.eslintrc.cjs`	ESLint JavaScript linting rules
`stylelint.config.mjs`	Stylelint CSS/SCSS linting rules
`prettier.config.mjs`	Prettier code formatting rules
`phpcs.xml`	PHP CodeSniffer rules
`twig_cs.php`	Twig coding standards config
`.twig-cs-fixer.php`	Twig CS Fixer configuration
`lint-staged.config.mjs`	Pre-commit lint configuration
`.editorconfig`	Editor formatting consistency

All linting tools run as part of the build process:

# Run all quality checks
npm run build

# Run individual checks
npm run lint           # ESLint + Stylelint
npm run lint:script    # ESLint only
npm run lint:style     # Stylelint only
npm run format         # Prettier formatting
npm run phpcs          # PHP CodeSniffer
npm run twigcs         # Twig coding standards

# Run all quality checks
npm run build

# Run individual checks
npm run lint           # ESLint + Stylelint
npm run lint:script    # ESLint only
npm run lint:style     # Stylelint only
npm run format         # Prettier formatting
npm run phpcs          # PHP CodeSniffer
npm run twigcs         # Twig coding standards

Bash

Development workflow

1. Start development server:

npm run dev

npm run dev

Bash

This compiles assets in watch mode with fast refresh enabled.

2. Edit files in `src/` (scripts, styles, blocks)

3. Build for production:

npm run build

npm run build

Bash

This runs linting and produces minified, optimized assets in build/.

5. Commit changes according to your repository policy (source files).

Fast refresh requirements

For fast refresh to work correctly, ensure your wp-config-local.php contains:

define( 'SCRIPT_DEBUG', true );
define( 'WP_ENVIRONMENT_TYPE', 'development' );

define( 'SCRIPT_DEBUG', true );
define( 'WP_ENVIRONMENT_TYPE', 'development' );

PHP

The theme detects development mode by checking for the presence of build/runtime.js.

Icons module (optional)

Chisel supports an optional icons module for SVG sprite generation. To enable:

1. Add `--use-icons-module` to npm scripts:

{
  "scripts": {
    "start": "chisel-scripts start --experimental-modules --use-icons-module",
    "build-scripts": "chisel-scripts build --experimental-modules --use-icons-module"
  }
}

{
  "scripts": {
    "start": "chisel-scripts start --experimental-modules --use-icons-module",
    "build-scripts": "chisel-scripts build --experimental-modules --use-icons-module"
  }
}

JSON

2. Define the constant in your theme’s `functions.php`

define( 'CHISEL_USE_ICONS_MODULE', true );

define( 'CHISEL_USE_ICONS_MODULE', true );

PHP

3. Set `$use-icons-module` scss variable to true in `src/design/settings/_index.scss`:

// Icons module. Also requires packacke.json and functions.php configuration.
$use-icons-module: true;

// Icons module. Also requires packacke.json and functions.php configuration.
$use-icons-module: true;

SCSS

4. Place SVG source files in `assets/icons-source/`

The build system will generate an optimized SVG sprite in assets/icons/

Modern Webpack Setup

Overview

Webpack Configuration

Source structure

Scripts (src/scripts/)

Styles (src/styles/)

Design Tokens (src/design/)

Blocks

Outputs and assets

Build directory (build/)

Static assets (assets/)

What the pipeline provides

Development mode (npm run dev)

Production mode (npm run build)

WordPress Interactivity API Support

Quality gates / Configuration files

Development workflow

1. Start development server:

2. Edit files in src/ (scripts, styles, blocks)

3. Build for production:

5. Commit changes according to your repository policy (source files).

Fast refresh requirements

Icons module (optional)

1. Add --use-icons-module to npm scripts:

2. Define the constant in your theme’s functions.php

3. Set $use-icons-module scss variable to true in src/design/settings/_index.scss:

4. Place SVG source files in assets/icons-source/

Do you like Chisel?

Scripts (`src/scripts/`)

Styles (`src/styles/`)

Design Tokens (`src/design/`)

Build directory (`build/`)

Static assets (`assets/`)

Development mode (`npm run dev`)

Production mode (`npm run build`)

2. Edit files in `src/` (scripts, styles, blocks)

1. Add `--use-icons-module` to npm scripts:

2. Define the constant in your theme’s `functions.php`

3. Set `$use-icons-module` scss variable to true in `src/design/settings/_index.scss`:

4. Place SVG source files in `assets/icons-source/`