@ideasonpurpose/build-tools-wordpress

Version 2.6.2

Build scripts and dependencies for IOP's WordPress development environments.

About This Package

These tools were migrated from our Docker-based WordPress build tools to speed up development and began the process of moving our build tools away from webpack. Gathering dependencies also simplifies the package.json and configuration files in host projects, making those slightly more manageable.

Versioned Releases

IOP versions our themes so every release creates a clear rollback snapshot. To accomplish this, every milestone build is generated into a versioned directory. This works well for themes where only one can be active, but fails for plugins where multiple versions can be simultaneously enabled so long as their directory names are different.

To work around this, a type property can be added to the config file. When type is plugin, builds will not add the version to directory names.

Optional Config

Each project may optionally include an ideasonpurpose.config.js file in the same directory as package.json. Any settings in this file will override the defaults.

SVG Processing

Webpack handles SVG files differently based on import context:

• In SCSS files: SVGs referenced via url('file.svg') are inlined as data URIs if under 4KB, otherwise emitted as separate files in the output directory.

• In JS/TSX files:

  • With ?url query (e.g., import svg from 'file.svg?url'): Treated as assets, inlined as data URIs if under 4KB, else files.
  • Without ?url: Converted to React components using @svgr/webpack for direct JSX usage.

Data URIs are generated as data:image/svg+xml,<url-encoded-content> using more efficient URL-encoding, not base64.

Local Development

Because this project makes use of bin scripts, conventional npm link workflows won't work correctly. To work on this code in a development project, change the project's package.json to install from a local file path, probably something like this:

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

Running a simple watch script to re-install on changes will make things somewhat seamless:

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

Additional Notes

This project expects an entirely ES Module based environment and specifies all dependencies using standard ESM import syntax. Projects importing this file should set "type": "module" in their package.json files.

Sass imports

Sass can import stylesheet files directly from npm packages. Use the full path from node_modules like this:

@use "@ideasonpurpose/build-tools-wordpress/example/package-style";

Publishing to npm

A GitHub action will auto-publish version-tagged releases to npm. In order to publish, the repository must have an NPM_TOKEN secret set with the token from npm. Log into npmjs.org with a publish-authorized account, then find the token page linked from the Profile page sidebar. Generate a new token and update the repository secret.

Brought to you by IOP

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