@ideasonpurpose/build-tools-wordpress

Version 2.10.11

Build scripts and shared dependencies for WordPress development. Used in production at Ideas On Purpose.

This package centralizes Webpack configuration, asset pipelines, and helper CLIs so host projects stay fast and thin: a small package.json, a one-line webpack.config.js, and an optional config file.

Use with IOP's lightning-fast Docker-based WordPress development image.

Requirements

Node.js 22.15+ (required by webpack-dev-server 6; ESM only)

Install

npm install -D @ideasonpurpose/build-tools-wordpress

Typical host scripts (see boilerplate/package.json):

{
  "type": "module",
  "scripts": {
    "prebuild": "npm run clean",
    "build": "NODE_ENV=production webpack",
    "postbuild": "npm run zip",
    "start": "webpack serve",
    "zip": "iop-build-zip-archive"
  },
  "devDependencies": {
    "@ideasonpurpose/build-tools-wordpress": "^2.10.11"
  },
  "prettier": "@ideasonpurpose/prettier-config",
  "stylelint": {
    "extends": "@ideasonpurpose/stylelint-config"
  }
}

Prettier and Stylelint configs are re-exported from this package’s dependencies so hosts can extend them without separate installs.

Quick start

1. Point Webpack at this package

// webpack.config.js
export { webpackConfig as default } from "@ideasonpurpose/build-tools-wordpress";

2. Source files

The project should have these files:

wp-content/themes/<package-name>/
  src/
    js/main.js
    js/admin.js
    js/editor.js
    styles/      # formerly 'sass'

3. Run

npm run dev

4. Build

Configuration

Optional config is loaded with cosmiconfig under the name ideasonpurpose — typically ideasonpurpose.config.js next to package.json. Values merge over defaults.

Defaults

Option	Default	Notes
`src`	`./wp-content/themes/<name>/src`	`<name>` from host `package.json`
`dist`	`./wp-content/themes/<name>/dist`
`entry`	`["./js/main.js", "./js/admin.js", "./js/editor.js"]`	Relative to `src`. String, array, or object
`publicPath`	`/wp-content/themes/<name>/dist/`
`esTarget`	`"es2020"`	Passed to esbuild-loader / minimizer
`devtool`	`"source-map"`
`proxy`	`"wordpress"`	Dev-server proxy target (Docker service name, URL, IP, or `true` to auto-detect)
`manifestFile`	`"./dependency-manifest.json"`	Written into `dist`
`type`	(unset / theme)	Set `"plugin"` to change archive naming

Paths resolve relative to the config file (or package.json if no config file is found).

Entry shapes

// Array → basenames become entry keys (overlapping basenames merge)
entry: ["./js/main.js", "./js/admin.js"];

// String → single entry
entry: "./js/main.js";

// Object → passed through
entry: { app: "./js/main.js", admin: "./js/admin.js" };

Themes vs plugins

Releases are versioned so each build is a clear rollback snapshot. For themes, zip archives use a versioned folder name (my-theme-1.2.3). That fails for plugins, where multiple versions can be active if directory names differ.

Set type: "plugin" to omit the version from the archive directory name:

// ideasonpurpose.config.js
export default {
  type: "plugin",
  src: `./wp-content/plugins/my-plugin/src`,
  dist: `./wp-content/plugins/my-plugin/dist`,
  publicPath: `/wp-content/plugins/my-plugin/dist/`,
  entry: ["./js/main.js"],
};

What the build does

Area	Implementation
Bundler	Webpack 5
JS/TS/JSX	esbuild-loader
CSS	Sass (sass-embedded, modern compiler API), PostCSS (autoprefixer; cssnano in production)
Images	`asset` modules + Sharp via image-minimizer-webpack-plugin
SVG	Asset / data-URI or React components via @svgr/webpack (see below)
Copy	Static files from `src` (blocks, fonts, etc. handled specially)
WordPress	`@wordpress/dependency-extraction-webpack-plugin` + custom dependency manifest
Dev server	Hot reload, live reload on PHP/HTML/SVG/JSON, reverse proxy to local WP
Production	Content hashes, minification, optional bundle analyzer report, zip via `iop-build-zip-archive`

Sass loadPaths include src/sass, src/styles, and the project node_modules, so packages can be imported by name:

@use "some-npm-package/styles";

Dev server

Proxies the site to a local WordPress container (default Docker service name wordpress) when proxy is enabled
Watches theme PHP/HTML/SVG/JSON for full reload
GET /webpack/reload triggers a client refresh (useful from PHP or external tools)

Zip archives

iop-build-zip-archive packs the theme/plugin parent of src into _builds/<name>[-version].zip. Version suffix is skipped when type is "plugin".

SVG processing

Webpack treats SVGs differently by context:

In SCSS (url('file.svg')): inlined as a data URI if under 4KB, otherwise emitted as a file.
In JS/TSX:
- import svg from 'file.svg?url' — asset URL / data URI (4KB threshold)
- import Icon from 'file.svg?react' — React component via SVGR
- bare import Icon from 'file.svg' from .jsx/.tsx — React component (default)

React SVG components use dimensions: false (no fixed width/height; viewBox kept) so they scale with CSS.

Data URIs use URL-encoding (data:image/svg+xml,<encoded>), not base64.

SVGO and VS Code

SVGO and our preferred config/svgo.config.mjs ship with the package, plus a stdin formatter for the editor.

Install SVG Language Mode ID and Custom Local Formatters, then in settings.json:

{
  "[svg]": {
    "editor.defaultFormatter": "jkillian.custom-local-formatters",
    "editor.formatOnSave": false
  },
  "customLocalFormatters.formatters": [
    {
      "command": "iop-vscode-svgo",
      "languages": ["svg"]
    }
  ]
}

The formatter loads a project svgo.config if present, otherwise falls back to this package’s config.

Notes:

VS Code treats SVG as XML by default; the language-mode extension is required for the [svg] scope.
Formatting fails if editor.formatOnSaveMode is "modifications" (range formatting does not send a full document).

IOP SVGO defaults (config/svgo.config.mjs):

Pretty-print with 4-space indent
Preserve ID names (cleanupIds: false)
Custom: copy width/height from viewBox onto <svg> when missing
Custom: remove top-level fill="none"
removeUselessStrokeAndFill with removeNone: true

WP-CLI

The WordPress base image includes wp-cli and all commands can be run on the image using the wp-cli npm script. Commands with flags need to include a double-hyphen, but we just include them for everything. These all work as expected:

# list users
npm run wp-cli -- wp user list

# Update to pre-release
npm run wp-cli -- wp core update --version=7.1-RC4

# Add a user for e2e testing
wp user create test test@example.com --role=administrator --user_pass=test123

CLI tools

Command	Purpose
`iop-build-zip-archive`	Zip theme/plugin into `_builds/`
`iop-build-port-reporter`	Print discovered local WordPress URL/port (Docker)
`iop-project-refresh`	Sync host tooling from package boilerplate (`package.json` scripts, `docker-compose.yml`, `.gitignore`, dirs, optional templates). Flags: `--dry-run`, `--force` (allow dirty git tree)
`iop-html-php-prettier`	Experimental mixed HTML/PHP formatter
`iop-format-wp-block-pattern`	Experimental WordPress block-pattern PHP formatter
`iop-vscode-svgo`	SVGO over stdin for editor formatters

`iop-html-php-prettier`

Double-formats mixed HTML and PHP (WordPress templates): PHP is tokenized, the file is formatted as HTML with Prettier, tokens are restored, then PHP is formatted with @prettier/plugin-php.

A faster rewrite is in progress: Format Mixed PHP and HTML.

npx iop-html-php-prettier path/to/file.php

Also accepts STDIN → STDOUT for Custom Local Formatters:

"customLocalFormatters.formatters": [
  {
    "command": "npx iop-html-php-prettier",
    "languages": ["php"]
  }
]

`iop-format-wp-block-pattern`

Formats WordPress block pattern PHP: readable block markup, expanded JSON in  comments, and whitespace tuned for the block editor.

npx iop-format-wp-block-pattern path/to/pattern.php

`iop-project-refresh`

Updates an existing project’s tooling from this package’s boilerplate/ and tooling/ trees. Safe defaults: refuses a dirty git working tree unless --force; use --dry-run to preview.

npx iop-project-refresh
npx iop-project-refresh --dry-run
npx iop-project-refresh --force

Local development (this package)

Bin scripts break conventional npm link. In a consumer project, depend on a local path instead:

"devDependencies": {
  "@ideasonpurpose/build-tools-wordpress": "file:../../build-tools-wordpress"
}

Reinstall on change:

cd dev-project-working-dir
npx chokidar-cli "../../build-tools-wordpress/**/*" -c "npm install"

Publishing

Version-tagged releases publish to npm via GitHub Actions (OIDC trusted publishing). See CHANGELOG.md.

If the workflow needs a classic token instead, set repository secret NPM_TOKEN from an npm publish-capable account.

Brought to you by IOP

	This project is actively developed and used in production at Ideas On Purpose.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
bin		bin
boilerplate		boilerplate
config		config
example		example
lib		lib
test		test
tooling		tooling
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Uh oh!

Repository files navigation

@ideasonpurpose/build-tools-wordpress

Version 2.10.11

Requirements

Install

Quick start

1. Point Webpack at this package

2. Source files

3. Run

4. Build

Configuration

Defaults

Entry shapes

Themes vs plugins

What the build does

Dev server

Zip archives

SVG processing

SVGO and VS Code

WP-CLI

CLI tools

`iop-html-php-prettier`

`iop-format-wp-block-pattern`

`iop-project-refresh`

Local development (this package)

Publishing

Brought to you by IOP

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

@ideasonpurpose/build-tools-wordpress

Version 2.10.11

Requirements

Install

Quick start

1. Point Webpack at this package

2. Source files

3. Run

4. Build

Configuration

Defaults

Entry shapes

Themes vs plugins

What the build does

Dev server

Zip archives

SVG processing

SVGO and VS Code

WP-CLI

CLI tools

iop-html-php-prettier

iop-format-wp-block-pattern

iop-project-refresh

Local development (this package)

Publishing

Brought to you by IOP

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`iop-html-php-prettier`

`iop-format-wp-block-pattern`

`iop-project-refresh`