@plaudit/webpack-extensions 2.84.0 → 2.84.1

package/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.84.1] - 2026-02-11
+### Fixed
+- Typedef compatibility issues with Webpack 5.105.0
+
 ## [2.84.0] - 2026-01-30
 ### Added
 - Support for using `lazyLoader` on plain entrypoints

package/USER-GUIDE.md

@@ -0,0 +1,589 @@
+<!-- TOC -->
+* [General Information](#general-information)
+  * [What is This?](#what-is-this)
+  * [Why is This?](#why-is-this)
+  * [How to Read This Guide](#how-to-read-this-guide)
+    * [General](#general)
+    * [Paths](#paths)
+    * [Examples](#examples)
+  * [Best Practices](#best-practices)
+    * [Folder Structure](#folder-structure)
+    * [Blocks](#blocks)
+    * [Extensions](#extensions)
+    * [Plain Assets](#plain-assets)
+    * [Configuration](#configuration)
+  * [Quick Start](#quick-start)
+    * [1. Create webpack.config.js](#1-create-webpackconfigjs)
+    * [2. Set Up Your File Structure](#2-set-up-your-file-structure)
+    * [3. Include unified-loader.php in Your Plugin](#3-include-unified-loaderphp-in-your-plugin)
+    * [4. Run Build Commands](#4-run-build-commands)
+  * [Using Asset Handles in PHP](#using-asset-handles-in-php)
+    * [Handle Format](#handle-format)
+    * [Finding Your Handles](#finding-your-handles)
+    * [Example: Manual Enqueue with Localization](#example-manual-enqueue-with-localization)
+  * [Common Patterns](#common-patterns)
+    * [Pattern 1: Frontend-Only Script](#pattern-1-frontend-only-script)
+    * [Pattern 2: Conditional Loading (Manual Enqueue)](#pattern-2-conditional-loading-manual-enqueue)
+    * [Pattern 3: Admin-Only Styles](#pattern-3-admin-only-styles)
+    * [Pattern 4: Block Editor Styles](#pattern-4-block-editor-styles)
+* [Reference](#reference)
+  * [Root Options](#root-options)
+  * [Per-Entrypoint Options](#per-entrypoint-options)
+    * [Boolean-form](#boolean-form)
+    * [String-form](#string-form)
+    * [Object-form](#object-form)
+  * [Additional Dependencies](#additional-dependencies)
+    * [In webpack.config.js (per entrypoint)](#in-webpackconfigjs-per-entrypoint)
+    * [First-line comment in the entry source file](#first-line-comment-in-the-entry-source-file)
+  * [Entrypoint Types](#entrypoint-types)
+    * [Blocks](#blocks-1)
+      * [File Structure](#file-structure)
+      * [Notes](#notes)
+      * [Per-Entrypoint Options](#per-entrypoint-options-1)
+    * [Extensions](#extensions-1)
+      * [File Structure](#file-structure-1)
+      * [File Naming](#file-naming)
+      * [Notes](#notes-1)
+      * [Per-Entrypoint Options](#per-entrypoint-options-2)
+    * [Plain](#plain)
+      * [File Structure](#file-structure-2)
+      * [Per-Entrypoint Options](#per-entrypoint-options-3)
+        * [The Locations Object](#the-locations-object)
+  * [WordPress Types](#wordpress-types)
+    * [WordPress Script Args](#wordpress-script-args)
+  * [Supported File Types](#supported-file-types)
+  * [Need Help?](#need-help)
+<!-- TOC -->
+
+# General Information
+
+## What is This?
+
+This webpack wrapper automates the process of compiling and loading assets for WordPress sites.
+It is guaranteed to work on all Plaudit-made themes and plugins and can be dropped into most non-Plaudit-made plugins and themes with minimal edits to their structure.
+
+It does this by taking advantage of patterns in how WordPress expects assets to be provided combined with a dash of template-generated PHP.
+
+You only need to configure `webpack.config.js` and run `pnpm run watch` or `pnpm run build`.
+
+## Why is This?
+
+This webpack wrapper started out as a method of mapping the source names to destination names automatically. Over time, it has expanded to automate all the mapping that WordPress expects developers to do manually.
+Its output has *significant* performance boosts compared to what following WordPress's guides will get by eliminating *all* folder iteration and replacing the `O(N)` asset configuration loading that following WordPress' guides produces with one that requires only a single file per entrypoint category (root loader, image/font/etc assets, blocks, extensions, and plain).
+
+In addition to the improved loading performance and working as a vehicle for distributing improvements to the loading code across sites (even when the loading code is in unmanaged themes and plugins), it also provides a few minor enhancements over WordPress' own webpack wrapper:
+- CSS versioning
+  - While WordPress *appears* to generate version hashes for CSS files, they aren't actually based on the contents of the CSS files
+- Automatic filename conflict resolution
+  - This one isn't strictly necessary, but if you want to have both `view-script.ts` and `view-style.pcss`, this'll make it work!
+  - This conflict handling also extends to taking steps to avoid assets conflicting with ones from other plugins or themes
+- Non-bundled asset versioning (images, fonts, etc)
+  - This is a standard webpack feature. It's just disabled by how WordPress's stuff
+
+When combined with [`pnpx @plaudit/scaffold`](https://bitbucket.org/plaudit/scaffold/src/main/README.md), no manual configuration should be needed for 99% of client work.
+However, if you need to do something unusual or just want to know what everything in the config file actually does, this guide is for you!
+
+## How to Read This Guide
+### General
+- When in doubt, roll with the default
+- Due to naming differences, you will sometimes see `Entrypoint` being used to refer to things in the `src` object
+- For brevity, "assets" will be used in place of "scripts and styles"
+- This guide assumes that you are using the most recent versions of the loader logic
+- This guide is primarily informational, so you will be seeing the *every* flag, not just "recommended" ones
+- If what you are looking at seems weirdly specific or excessively complicated, check if it's marked with **[Advanced]** or **[Legacy]**. There are a lot of highly situational and/or weird flags that are only useful when hyper-optimizing asset loading
+
+### Paths
+- Any time that `src` is referenced in a path, it should be replaced with the value of `srcDir` in your WebPack file
+  - To be crystal clear, the value of `srcDir` *should be* `src`; however, this might not be the case in some inherited or older code
+- Any time that `dist` is referenced in a path, it should be replaced with the value of `outputDir` in your WebPack file
+  - As with `src`, the value of `outputDir` *should be* `dist`; however, this might not be the case in some inherited or older code
+- Keys in the `src` *object* are all assumed to be paths relative to `srcDir` if it is specified or the folder in which the `webpack.config.js` file is located if it is not specified
+- Paths in values in the `src` *object* are all assumed to be paths relative to `outputDir` if it is specified or the folder in which the `webpack.config.js` file is located if it is not specified
+- All file names are informational placeholders. They can be whatever you want provided that they are web-safe (basically, don't do things like calling the email address block "✉️" and you'll be fine)
+
+### Examples
+- Any uses of `acme-my-plugin` should be replaced with your plugin or theme's kebab-case name (ex: `acme-my-plugin.wp-admin` => `plaudit-base.wp-admin`)
+
+---
+
+## Best Practices
+### Folder Structure
+- All folder and file names should be in kebab-case
+- Assets *should not* be in the root of the `src` folder. Assets that aren't block- or extension-bound should be in the `site` folder (or in a folder named after where they'll be used like, `admin` or `map-page`)
+
+### Blocks
+- Block folder names *should* match the local portion of their name (ex: `plaudit-query-loop-maps/address-wrapper` should be stored in `address-wrapper`)
+
+### Extensions
+- Extensions *should not* be repeated for multiple blocks. If you find that happening, move it to a site-level asset that gets loaded at the appropriate time.
+  - This can be done pretty easily via `pnpm dlx @plaudit/scaffold add site asset`
+- Extensions *should not* be applied to site-specific blocks (basically, only use extensions for stuff that is from WordPress, pulled in via composer, or is from a 3rd party)
+
+### Plain Assets
+- Plain assets *should be your last option*. They have the least amount of granularity in where they can be included, which can easily lead to serving bloated code.
+- Just because you *can* have multiple folders doesn't mean that you *should*
+
+### Configuration
+- A good configuration file is one that does not include any unnecessary configuration (ex: if you won't be manually enqueuing an asset or referencing it elsewhere, don't give it a named handle)
+
+---
+
+## Quick Start
+
+### 1. Create webpack.config.js
+This is automatically created and populated when running any [scaffold](https://bitbucket.org/plaudit/scaffold/src/main/README.md) command.
+
+The config tells webpack **what** to build and **where** to load it in WordPress.
+
+```javascript
+module.exports = require("@plaudit/webpack-extensions/wordpress-scripts-wrapper")({
+	src: {
+	  // Build all blocks in src/blocks/
+		"blocks": true,
+    
+	  // Build block extensions from src/extensions/
+		"extensions": {directoryLayout: 'extensions'},
+
+	  // Auto-load in the head on frontend
+		"site/index-header.ts": {
+			locations: {
+				clientView: true,
+				registerScriptArgs: false
+			}
+		},
+    
+	  // Auto-load at the bottom of the body on frontend
+		"site/index-footer.ts": {
+			locations: {
+				clientView: true,
+				registerScriptArgs: 'lazy'
+			}
+		},
+	  // Auto-load in admin
+		"site/wp-admin.ts": {
+			locations: {
+				admin: true
+			}
+		},
+	  // Auto-load in admin
+		"site/wp-admin.pcss": {
+			locations: {
+				admin: true
+			}
+		},
+	  // Auto-load in the block editor
+		"site/block-editor.pcss": {
+			locations: {
+				clientEditor: true
+			}
+		},
+	  // Auto-load in the head on frontend
+		"site/public.pcss": {
+			locations: {
+				clientView: true
+			}
+		},
+	  // A script that can be enqueued via its handle, but is not autoloaded
+	  "site/manually-loaded.ts": {
+		  locations: "plaudit-theme/manually-loaded-script"
+	  }
+	},
+	useWebpackResourceFiltering: true, // Always use this!
+	extensionsVersion: 3,
+	plainEntrypointsVersion: 2,
+	srcDir: "src", // Always use this!
+	outputDir: "dist", // Always use this!
+	useUnifiedLoader: true, // Always use this!
+	variables: {
+		font_size: 16 // Required for pxAsRem to work; replace the 16 with your site's base font size
+	}
+});
+```
+
+### 2. Set Up Your File Structure
+
+**Blocks** (subdirectories with block.json):
+- **Config:** `'blocks': true`
+- **File Structure:** [See Here](#file-structure)
+
+**Extensions** (flat files that modify existing blocks):
+- **Config:** `'extensions': {directoryLayout: 'extensions'}`
+- **File Structure:** [See Here](#file-structure-1)
+
+**Other Files** (scripts, styles):
+- **Config:** List each file individually in `src` object
+- **File Structure:** [See Here](#file-structure-2)
+
+### 3. Include unified-loader.php in Your Plugin
+After building, include the generated loader file in the plugin's main PHP file. [Scaffold](https://bitbucket.org/plaudit/scaffold/src/main/README.md) commands will offer to add this to the plugin file if needed.
+
+**Example:**
+```php
+<?php
+/**
+ * Plugin Name: My Plugin
+ */
+
+@include_once __DIR__ . '/dist/unified-loader.php';
+```
+
+This file automatically:
+- Registers all your scripts and styles
+- Enqueues them in the right places
+- Handles dependencies
+- Sets up blocks and extensions
+
+### 4. Run Build Commands
+While you *can* manually run these commands, using `theapp pack dev/watch/build` is preferred
+
+```bash
+pnpm run watch   # Development mode (watches for changes)
+pnpm run build   # Production build
+```
+
+---
+
+## Using Asset Handles in PHP
+
+After building, each asset gets a handle you can reference in PHP.
+
+### Handle Format
+
+**Plain:** `{prefix}.{filename}`
+- Example: `acme-my-plugin.admin-editor`
+
+**Blocks:** `{prefix}_blocks_{block-name}-{type}`
+- Example: `acme-my-plugin_blocks_hero-banner-editor-script`
+  - Block handles are subject to runtime-change, so they cannot be safely referenced
+
+**Extensions:** `{prefix}_block-extensions_{block-name}-{type}`
+- Example: `acme-my-plugin_block-extensions_hero-banner-editor-script`
+  - Extension handles are subject to runtime-change, so they cannot be safely referenced
+
+### Finding Your Handles
+
+**Best way:** Check the generated loader files after building:
+- `dist/blocks/blocks-loader.php`
+- `dist/extensions/extensions-loader.php`
+- The first argument of the `wp_register_script` and `wp_register_style` calls in `dist/plain-entrypoints-loader.php` 
+
+### Example: Manual Enqueue with Localization
+
+```php
+<?php
+// For manually-enqueued assets
+add_action('admin_enqueue_scripts', function($hook) {
+	if ($hook === 'post.php') {
+		// Localize data first (optional)
+		wp_localize_script('acme-my-plugin.admin-editor', 'myData', [
+			'ajaxUrl' => admin_url('admin-ajax.php'),
+			'nonce' => wp_create_nonce('my_ajax_action'),
+		]);
+		
+		// Then enqueue
+		wp_enqueue_script('acme-my-plugin.admin-editor');
+		wp_enqueue_style('acme-my-plugin.admin-editor');
+	}
+});
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Frontend-Only Script
+
+```javascript
+// webpack.config.js
+src: {
+	'site/public.ts': {
+		locations: {
+			clientView: true,
+			registerScriptArgs: 'lazy'
+		}
+	}
+}
+```
+
+### Pattern 2: Conditional Loading (Manual Enqueue)
+
+```javascript
+// webpack.config.js
+src: {
+	'post-editor.ts': {
+		locations: { register: true }  // Don't auto-load
+	}
+}
+```
+
+```php
+<?php
+// In your plugin
+add_action('admin_enqueue_scripts', function($hook) {
+	if ($hook === 'post.php') {
+		wp_enqueue_script('acme-my-plugin.post-editor');
+	}
+});
+```
+
+### Pattern 3: Admin-Only Styles
+
+```javascript
+src: {
+	'admin/styles.pcss': {
+		locations: { admin: true }
+	}
+}
+```
+
+### Pattern 4: Block Editor Styles
+
+```javascript
+// webpack.config.js
+src: {
+	'editor/custom-editor-styles.pcss': {
+		locations: { clientEditor: true }
+	}
+}
+```
+
+---
+
+# Reference
+
+## Root Options
+| Option                             | Type      | Default      | Description                                                                                                                                                                                  |
+|------------------------------------|-----------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `src`                              | `object`  | **Required** | Files/directories to process (see the next section for what you can put in here)                                                                                                             |
+| `srcDir`                           | `string`  | `""`         | Source directory (**Required** on new sites)                                                                                                                                                 |
+| `outputDir`                        | `string`  | `""`         | Output directory (**Required** on new sites)                                                                                                                                                 |
+| `useUnifiedLoader`                 | `boolean` | `false`      | Generate unified-loader.php (always set to `true` on new sites!)                                                                                                                             |
+| `useWebpackResourceFiltering`      | `boolean` | `false`      | Generates versioned copies of images, fonts, etc (always set to `true` on new sites!)                                                                                                        |
+| `plainEntrypointsVersion`          | `1\|2`    | `1`          | Use 2 for new sites                                                                                                                                                                          |
+| `extensionsVersion`                | `1\|2\|3` | `1`          | Use 3 for new sites                                                                                                                                                                          |
+| `verbose`                          | `boolean` | `false`      | Verbose logging                                                                                                                                                                              |
+| `variables`                        | `object`  | Auto         | CSS/JS variables. If a variables.js file is present, this will automatically load from that file                                                                                             |
+| `onlyRunPostCSSOnPCSS`             | `boolean` | `false`      | If true, the PostCSS processor will not be run on CSS files. This is true for all new sites and can be safely enabled on most sites if desired.                                              |
+| `assumeGlobalizedPlauditLibraries` | `boolean` | `true`       | **[Advanced]** When `false`, normally-externalized plaudit libraries will be included.<br>**DO NOT USE THIS. IF YOU SEE IT BEING USED, CONTACT JOSH**                                        |
+| `externals`                        | `object`  | -            | **[Advanced]** Allows dependencies to be marked as external. This prevents them from being included in the bundle under the assumption that they will be provided via an alternate mechanism |
+| `targetHandlePrefix`               | `string`  | Auto         | **[Legacy]** Prefix for handles. Auto-detected from composer.json if omitted. Do not set this unless absolutely necessary                                                                    |
+
+---
+
+## Per-Entrypoint Options
+This section covers the shared options for entrypoints. See the [Entrypoint Types](#entrypoint-types) section for options specific to individual types
+
+### Boolean-form
+- This is only available if `outputDir` has been set
+- The only supported value is `true` and only works for `blocks` and `plain` entrypoints. It means that every value will have its default value
+- In the case of `plain` entrypoints, they will need to be manually enqueued, so using it is not advised - it's just *technically* possible
+- The reason that it doesn't work for `extensions` entrypoints is that `extensions` are not reliably distinguishable from `blocks` and `blocks` is the default entrypoint type
+- The output directory will be the same as the source directory except that it will be under the `outputDir`
+
+### String-form
+- This is only available for `blocks` and `plain` entrypoints
+- This is equivalent to `{destination: <value here>}`
+- It is otherwise the same as the [Boolean form](#boolean-form)
+- The value is treated as the output directory relative to `outputDir` if it is specified or the folder in which the `webpack.config.js` file is located if it is not specified
+
+### Object-form
+- This is necessary for `extensions` entrypoints and the preferred form for `plain` entrypoints
+- In general, `blocks` entrypoints should use either [Boolean](#boolean-form)- or [String](#string-form)-form
+- `plain` entrypoints have additional options available. They can be found in its [entrypoint type section](#plain)
+
+| Option                             | Type                        | Default                                      | Description                                                                                                                                                                                                                                                    |
+|------------------------------------|-----------------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `directoryLayout`                  | `blocks\|extensions\|plain` | Auto                                         | This should only be set for `extensions` entrypoints                                                                                                                                                                                                           |
+| `destination`                      | `string`                    | Auto when `outputDir` is set, none otherwise | **[Required when `outputDir` is not set]** Sets the output path<br>**This should not be set when `outputDir` is set**                                                                                                                                          |
+| `bundleAnalyzer`                   | `boolean`                   | `false`                                      | **[Advanced]** Enable bundle analyzer                                                                                                                                                                                                                          |
+| `lazyLoader`                       | `string`                    | -                                            | **[Advanced]** **For `blocks` and `extensions` entrypoints only**<br>Specifies the name of a function that must be called in order to load the entrypoint<br>See [The Locations Object](#the-locations-object) for how to achieve this for `plain` entrypoints |
+| `assumeGlobalizedPlauditLibraries` | `boolean`                   | Root Value                                   | **[Advanced]** When `false`, normally-externalized plaudit libraries will be included.<br>**DO NOT USE THIS. IF YOU SEE IT BEING USED, CONTACT JOSH**                                                                                                          |
+
+---
+
+## Additional Dependencies
+
+When WordPress registers or enqueues a script or style, it accepts a **dependencies** argument: an array of handles that must be loaded before the asset. This library discovers most dependencies from your imports; however, for any dependency that is not imported (i.e., a script provided by another plugin that your bundle expects to be present at runtime), you can declare **additional dependencies** so they are included in the generated loader.
+
+You can specify additional dependencies in either of two ways (or both - they are merged).
+
+### In webpack.config.js (per entrypoint)
+
+Set `additionalDependencies` on the entrypoint config. This applies to **plain** entrypoints (object-form) and any entrypoint type that supports the per-entrypoint options table above.
+
+```javascript
+// webpack.config.js
+src: {
+	'site/checkout.ts': {
+		locations: { clientView: true },
+		additionalDependencies: ['axios', 'some-plugin/script-handle']
+	}
+}
+```
+
+Dependencies are WordPress script/style handles (strings). They will be passed through as the `deps` array when the asset is registered.
+
+### First-line comment in the entry source file
+
+In the **first line** of the entrypoint source file (e.g., your `.ts` or `.js` file), you can use a special comment. If that line starts with `//ADDITIONAL_DEPENDENCIES:` (with no space after the colon in the prefix), the rest of the line is treated as a comma-separated list of dependency handles and added to the entrypoint’s additional dependencies.
+
+```javascript
+//ADDITIONAL_DEPENDENCIES: axios, some-plugin/script-handle
+import { doCheckout } from './checkout-helpers';
+// ...
+```
+
+This is useful when you want the dependency list to live next to the code that relies on it, or when different entrypoints are built from the same config and you want to vary dependencies per file.
+
+If you use both methods for the same entrypoint, the dependencies from the config and from the first-line comment will be combined.
+
+---
+
+## Entrypoint Types
+
+### Blocks
+This was first entrypoint type added, and, due to how it integrates with WordPress, it both has and needs the least amount of configuration.
+In fact, under most circumstances, the proper configuration value is just `true`.
+
+#### File Structure
+Subdirectories with block.json files
+```
+src/blocks/
+├── hero-banner/
+│   ├── block.json
+│   ├── index.ts
+│   ├── style.pcss
+│   └── template.php
+```
+
+#### Notes
+- Blocks **should** be created with `pnpm @plaudit/scaffold create block`
+- template.php and setup.php files are automatically loaded; however, they can be manually specified if desired
+- Script and Style files **must** be specified using the `file:./<path here>` syntax in the appropriate keys. See [WordPress' `block.json` reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/) for further details
+
+#### Per-Entrypoint Options
+The `blocks` entrypoint type doesn't have any.
+
+### Extensions
+This is used to associate additional assets with blocks that are not in control of the current project. This most-commonly means built-in WordPress blocks, but it can be used with any block.
+
+#### File Structure
+[Specially named files](#file-naming) in a single subdirectory of `src`
+```
+src/extensions/
+├── core-paragraph-view-script.ts
+└── core-paragraph-editor-style.pcss
+```
+
+#### File Naming
+Filenames **must** follow the pattern: `{kebab-case-block-name}-{type}.{ext}`
+- Valid values for `type` are:
+  - `script`, `editor-script`, `view-script`
+  - `style`, `editor-style`, `view-style`
+  - `script-module`, `view-script-module`
+  - `setup` (this allows for PHP code to be loaded only when certain blocks are enabled and is intended for use in plugins, not themes)
+- `ext` **must** be for a [supported file type](#supported-file-types) and **should** correspond with the extension type (basically, don't enqueue a `.css` file as a script)
+
+#### Notes
+- In order to have a directory be treated as `extensions`, the config **must** include `directoryLayout: 'extensions'`
+- Extensions **should** be created with `pnpm @plaudit/scaffold create extension`
+
+#### Per-Entrypoint Options
+The `extensions` entrypoint type doesn't have any.
+
+### Plain
+These entrypoints both support and need the largest amount of configuration. While all options will be listed here, the only one that you should need in sites is `locations`.
+
+While `plain` entrypoints *can* be used for directory-based loading, that is a deprecated feature and **must not** be used in new projects
+
+#### File Structure
+Files in arbitrary subdirectories of src
+```
+src/
+├── admin/
+│   ├── editor.ts
+│   └── editor.pcss
+├── site/
+│   ├── public.ts
+│   └── public.pcss
+```
+
+#### Per-Entrypoint Options
+| Option                   | Type                                       | Default | Description                                                                                                                                   |
+|--------------------------|--------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+| `locations`              | `object \| string \| fn(string) => string` | -       | Where/how to load the asset. See the [Locations Object](#the-locations-object) section below for how to use this                              |
+| `additionalDependencies` | `string[]`                                 | -       | **[Advanced]** Used to specify additional assets that the entrypoint depends on by handle                                                     |
+| `externalize`            | `string[]`                                 | -       | **[Advanced]** Specifies the object path at which the exports of the entrypoint should be emitted. This is used for creating shared libraries |
+| `withLegacyBlocksIn`     | `string`                                   | -       | **[Legacy]** Used to load legacy blocks that predate our use of `block.json`. This should **never** be used on new sites.                     |
+
+##### The Locations Object
+**String-form**:
+- Equivalent to `{handle: <value here>}`. See the Object-form section below for more information
+
+**Function-form**:
+- Equivalent to `{handle: <function here>}`. See the Object-form section below for more information
+
+**Object-form**:
+
+This is the form that *should* be used. It has two categories of keys: control flags and location identifiers. As such, they have been split out into two blocks
+
+**Control Flags:**
+
+| Key                  | Type                                                                     | Default | Description                                                                                                                                      |
+|----------------------|--------------------------------------------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| `handle`             | `string \| fn(string) => string`                                         | Auto    | The handle by which the entrypoint will be referenced. The function form is passed the default handle for manual tweaking                        |
+| `register`           | `boolean \| number`                                                      | `true`  | **[Advanced]** Whether the entrypoint should be registered at all or, if a number, the priority of the hook in which the registration will occur |
+| `registerScriptArgs` | `boolean` \| `'lazy'` \| [`WordPressScriptArgs`](#wordpress-script-args) | Auto    | The loading flags (strategy, in_footer, and fetchpriority) for the script.<br>'lazy' is an alias for `{strategy: 'defer', in_footer: true}`      |
+
+**Location Identifiers:**
+
+All location identifiers can be either a `boolean` or `number`. If they are a number, it sets the priority for the hook that is used to *enqueue* the resulting asset
+
+| Identifier     | Hook                          | Purpose                                                                                                                                                   |
+|----------------|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `clientView`   | `wp_enqueue_scripts`          | Enqueues the asset on every visitable webpage. Block- or extension-based registration should generally be preferred                                       |
+| `clientEditor` | `enqueue_block_editor_assets` | Enqueues the asset for use with the editor *shell*. Assets that should be used in the editor *content* must be enqueued manually (or be loaded by blocks) |
+| `blockAssets`  | `enqueue_block_assets`        | Enqueues the asset everywhere that block assets are enqueued. This includes *both* visitable webpages *and* the editor *content*                          |
+| `admin`        | `admin_enqueue_scripts`       | Enqueues the asset on every admin page; additionally supports `hook_name` mode (see below)                                                                |
+| `login`        | `login_enqueue_scripts`       | Enqueues the asset on the login page                                                                                                                      |
+| `analytics`    | `plaudit_enqueue_analytics`   | A special version of `clientView` that only fires if enqueuing analytics code is allowed. Requires the `Plaudit Analytics Integrations` plugin.           |
+| `customizer`   | `customizer_enqueue_scripts`  | **[Legacy]** Enqueues the asset on legacy customizer page. Don't use this one.                                                                            |
+
+**`hook_name` mode**
+- Allows the "hook name" (while WordPress calls it "hook name", it's actually the admin page identifier) to be used as an additional qualifier on whether the asset gets enqueued.
+- This is currently only supported for the `admin` location
+
+## WordPress Types
+### WordPress Script Args
+**Boolean-form:**
+
+If `true`, the script is emitted in the footer. Defaults to `false`.
+
+**Object-form:**
+
+| Option          | Type                              | Default     | Description                                                                                                                                                                                       |
+|-----------------|-----------------------------------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `strategy`      | `'defer' \| 'async' \| undefined` | `undefined` | Allows the script loading to be delayed. See [WordPress' docs](https://developer.wordpress.org/reference/functions/wp_register_script/#delayed-script-loading) for more information               |
+| `in_footer`     | `boolean \| undefined`            | `false`     | If `true`, enqueues the script at the end of the body. See [WordPress' docs](https://developer.wordpress.org/reference/functions/wp_register_script/#delayed-script-loading) for more information |
+| `fetchpriority` | `'auto' \| 'low' \| 'high'`       | `'auto'`    | **[Advanced]** Allows direct control of the script's fetchpriority.<br>WordPress does not currently have documentation for this option                                                            |
+
+---
+
+## Supported File Types
+
+| Group                     | Extensions                                                 |
+|---------------------------|------------------------------------------------------------|
+| **JavaScript/TypeScript** | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.mts`               |
+| **Stylesheets**           | `.css`, `.pcss` (PostCSS), `.scss`, `.sass`                |
+| **Assets**                | `.svg`, `.png`, `.jpg`, `.webp`, `.woff`, `.woff2`         |
+| **Special**               | `block.json`, `template.php`, `template.twig`, `setup.php` |
+
+---
+
+## Need Help?
+
+1. Enable verbose logging: `verbose: true` in config
+2. Check generated files in `dist/` folder
+3. Look at config files: `dist/**/config.php`
+4. Check `dist/unified-loader.php` for registered assets
+5. Review the README.md for technical details

package/build/plugins/AbstractBiPhasicGroupPlugin.d.ts

@@ -1,7 +1,7 @@
-import { Compilation, Compiler, type WebpackPluginInstance } from "webpack";
+import { Compilation, Compiler } from "webpack";
 import { PseudoSemaphore } from "../utils/pseduo-semaphore";
 import type { VerifiedPlauditWordpressWebpackConfig } from "../utils/common-config-helpers";
-import { type ParsedAssetJsonProvider } from "../shared";
+import { type ParsedAssetJsonProvider, WebpackPlugin } from "../shared";
 type TapWithAssetsJsonOptions = {
     name?: string;
     stage?: (typeof Compilation.PROCESS_ASSETS_STAGE_REPORT) | (typeof Compilation.PROCESS_ASSETS_STAGE_ANALYSE);
@@ -9,7 +9,7 @@ type TapWithAssetsJsonOptions = {
 };
 type TapWithAssetsJsonFn = Parameters<Compilation['hooks']['processAssets']['tapPromise']>[1];
 type TapWithParsedAssetsJsonFn = (parsedAssetJsonProvider: ParsedAssetJsonProvider, assets: Parameters<TapWithAssetsJsonFn>[0]) => Promise<void> | void;
-export declare abstract class AbstractBiPhasicGroupPlugin implements WebpackPluginInstance {
+export declare abstract class AbstractBiPhasicGroupPlugin implements WebpackPlugin {
     protected readonly config: VerifiedPlauditWordpressWebpackConfig;
     readonly group: string;
     private readonly semaphores;

package/build/plugins/BrowserSyncPlugin.d.ts

@@ -1,5 +1,6 @@
+import { type WebpackPlugin } from "../shared";
 import browserSync, { type BrowserSyncInstance } from "browser-sync";
-import type { Compiler, WebpackPluginInstance } from "webpack";
+import type { Compiler } from "webpack";
 export type PluginOptions = {
     reload: boolean;
     name: string;
@@ -7,7 +8,7 @@ export type PluginOptions = {
     injectCss: boolean;
     middlewareBuilder?: (options: browserSync.Options) => browserSync.Options['middleware'];
 };
-export declare class BrowserSyncPlugin implements WebpackPluginInstance {
+export declare class BrowserSyncPlugin implements WebpackPlugin {
     private static isBrowserSyncRunning;
     private static browserSyncPluginOptions?;
     private readonly pluginOptions;

package/build/plugins/MiniCSSExtractPluginErrorCleaner.d.ts

@@ -1,4 +1,5 @@
-import type { Compiler, WebpackPluginInstance } from "webpack";
-export declare class MiniCSSExtractPluginErrorCleaner implements WebpackPluginInstance {
+import type { Compiler } from "webpack";
+import type { WebpackPlugin } from "../shared";
+export declare class MiniCSSExtractPluginErrorCleaner implements WebpackPlugin {
     apply(compiler: Compiler): void;
 }

package/build/plugins/PackageConfigSanityChecker.d.ts

@@ -1,4 +1,5 @@
-import type { Compiler, WebpackPluginInstance } from "webpack";
-export declare class PackageConfigSanityChecker implements WebpackPluginInstance {
+import type { Compiler } from "webpack";
+import type { WebpackPlugin } from "../shared";
+export declare class PackageConfigSanityChecker implements WebpackPlugin {
     apply(compiler: Compiler): void;
 }

package/build/plugins/VariablesJSMonitorPlugin.d.ts

@@ -1,6 +1,7 @@
 import type { VerifiedPlauditWordpressWebpackConfig } from "../utils/common-config-helpers";
-import type { Compiler, WebpackPluginInstance } from "webpack";
-export declare class VariablesJSMonitorPlugin implements WebpackPluginInstance {
+import type { Compiler } from "webpack";
+import type { WebpackPlugin } from "../shared";
+export declare class VariablesJSMonitorPlugin implements WebpackPlugin {
     private readonly config;
     constructor(config: VerifiedPlauditWordpressWebpackConfig);
     apply(compiler: Compiler): void;

package/build/plugins/WPMLConfigBuilder.d.ts

@@ -1,6 +1,7 @@
+import { type WebpackPlugin } from "../shared";
 import { AbstractBiPhasicGroupAndEntryPlugin } from "./AbstractBiPhasicGroupAndEntryPlugin";
-import { type Compiler, type WebpackPluginInstance } from "webpack";
-export declare class WPMLConfigBuilderPlugin implements WebpackPluginInstance {
+import { type Compiler } from "webpack";
+export declare class WPMLConfigBuilderPlugin implements WebpackPlugin {
     private readonly destDir;
     private readonly referencePlugin;
     private static jsdomInstance?;

package/build/shared.d.ts

@@ -1,6 +1,6 @@
 import { PHPWriter } from "@plaudit/php-writer";
 import type { Options as PostcssFunctionsOptions } from "postcss-functions";
-import { AssetInfo, Compilation, type Configuration, Entrypoint, WebpackError } from "webpack";
+import { AssetInfo, Compilation, Configuration, Entrypoint, WebpackError, Compiler } from "webpack";
 export type ParsedAssetsJson = Record<string, {
     dependencies: string[];
     version: string;
@@ -78,6 +78,9 @@ export declare const enum SourceType {
     plain = "plain"
 }
 export declare function determineCurrentSourceType(dest: string | AdvancedOutputConfig, srcIsDirectory: boolean): SourceType;
+export interface WebpackPlugin {
+    apply(compiler: Compiler): void;
+}
 export type ObjectIndividualExternalDepConfig = {
     import?: string | [string, ...string[]];
     handle: string;

package/build/utils/common-config-helpers.d.ts

@@ -1,6 +1,6 @@
 import type { AbstractBiPhasicGroupAndEntryPlugin, EntryProvider } from "../plugins/AbstractBiPhasicGroupAndEntryPlugin";
 import type { AdditionalDependencyInjectorPlugin } from "../plugins/AdditionalDependencyInjectorPlugin";
-import { EntrypointFields, PlauditWordpressWebpackConfig, BlockEntrypointInfo, VerifiedAdvancedOutputConfig, MinimumViableMetadata } from "../shared";
+import { EntrypointFields, PlauditWordpressWebpackConfig, BlockEntrypointInfo, VerifiedAdvancedOutputConfig, MinimumViableMetadata, WebpackPlugin } from "../shared";
 import type { Compiler, Configuration, DynamicEntryPlugin, WebpackPluginInstance } from "webpack";
 import type WebpackRemoveEmptyScriptsPlugin from "webpack-remove-empty-scripts";
 export type VerifiedPlauditWordpressWebpackConfig = Required<Omit<PlauditWordpressWebpackConfig, 'variables' | 'src' | 'externals'>> & {
@@ -8,7 +8,7 @@ export type VerifiedPlauditWordpressWebpackConfig = Required<Omit<PlauditWordpre
     currentVariables: Record<string, any>;
 } & Pick<PlauditWordpressWebpackConfig, 'externals'>;
 export type CommonPluginConfig = {
-    plugins: (WebpackPluginInstance | ((this: Compiler, compiler: Compiler) => void))[];
+    plugins: (WebpackPluginInstance | WebpackPlugin | ((this: Compiler, compiler: Compiler) => void))[];
     removeEmptyScriptsPlugin: WebpackRemoveEmptyScriptsPlugin;
     makeAdditionalDependencyInjectorPlugin(referencePlugin: AbstractBiPhasicGroupAndEntryPlugin<any>): AdditionalDependencyInjectorPlugin;
 };

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@plaudit/webpack-extensions",
-  "version": "2.84.0",
+  "version": "2.84.1",
   "license": "SEE LICENSE IN LICENSE.md",
   "files": [
     "/build",
     "README.md",
     "LICENSE.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "USER-GUIDE.md"
   ],
   "exports": {
     "./wordpress-scripts-wrapper": "./build/wordpress-scripts-wrapper.js",
@@ -23,12 +24,11 @@
     }
   },
   "devDependencies": {
-    "@plaudit/gutenberg-api-extensions": "^2.84.3",
+    "@plaudit/gutenberg-api-extensions": "^2.85.0",
     "@types/browser-sync-webpack-plugin": "^2.2.5",
-    "@types/node": "^25.1.0",
+    "@types/node": "^25.2.3",
     "@types/postcss-functions": "^4.0.4",
     "@types/tapable": "^2.3.0",
-    "@types/webpack": "^5.28.5",
     "@types/webpack-sources": "^3.2.3",
     "postcss-load-config": "^4.0.2",
     "postcss-loader": "^7.3.4",
@@ -63,7 +63,7 @@
     "postcss-reporter": "^7.1.0",
     "postcss-simple-vars": "^7.0.1",
     "postcss-url": "^10.1.3",
-    "webpack": "^5.104.1",
+    "webpack": "^5.105.1",
     "webpack-remove-empty-scripts": "^1.1.1",
     "xml-formatter": "^3.6.7"
   },