@plaudit/webpack-extensions 3.15.1 → 3.16.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+## [3.16.0] - 2026-08-04
+### Added
+- Logic so that files and directories with names equal to "example" or "examples" or that include "example" as a name segment are skipped
+  - This is done to allow us to include example files
+  - This comes from version `2.95.0`
+- Updated the user guide with this information
+  - This comes from version `2.95.0`
+
+### Fixed
+- The TOC in the user guide being out of date
+
 ## [3.15.1] - 2026-07-20
 ### Fixed
 - A bug that caused all styles bound for editor use to be emitted as inline CSS
@@ -219,6 +230,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Legacy PostCSS features that have been integrated into modern CSS
 - `@extends` support
 
+## [2.95.0] - 2026-08-04
+### Added
+- Logic so that files and directories with names equal to "example" or "examples" or that include "example" as a name segment are skipped
+  - This is done to allow us to include example files
+- Updated the user guide with this information
+
 ## [2.94.1] - 2026-07-20
 ### Fixed
 - A bug that caused all styles bound for editor use to be emitted as inline CSS

package/USER-GUIDE.md

@@ -8,6 +8,7 @@
     * [Examples](#examples)
   * [Best Practices](#best-practices)
     * [Folder Structure](#folder-structure)
+    * [Enforced Naming Conventions](#enforced-naming-conventions)
     * [Blocks](#blocks)
     * [Extensions](#extensions)
     * [Plain Assets](#plain-assets)
@@ -104,7 +105,7 @@ However, if you need to do something unusual or just want to know what everythin
 - 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
+- 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
@@ -117,6 +118,10 @@ However, if you need to do something unusual or just want to know what everythin
 - 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`)
 
+### Enforced Naming Conventions
+- Directory and file names that start with a "~" are interpreted as "backup code" and are, therefore, not built.
+- File and directory names that are equal to "example" or "examples", or have "example" as a name segment (see [Location-Encoding Filenames](#location-encoding-filenames) for details on what a name-segment is) are treated as example code and are also not built
+
 ### 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`)
 
@@ -354,16 +359,17 @@ Notes on how to read the following table:
 - `(-|=)` means "this can be either a dash or an equal sign"
 - Pipe-separated items in parentheses means "any one of these items can go here"
 
-| Name               | Token                                                       | Usage                                                                                                                                                    |
-|--------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Enqueuing Location | `(enqueuing-location)[(-\|=)priority]`                      | This is a special section that is actually a collection of values. See the [Enqueuing Location](#enqueuing-location) section for more details            |
-| Type Override      | `script`, `style`, `script-module`                          | Can be used to override the detected of the asset. Must be the first token in the filename; if used directly, it is shorthand for `both-(Type Override)` |
-| Inline             | `inline[(-\|=)position]`, `strategy(-\|=)inline[-position]` | Indicates that the script should be inlined. `position` can be either `before` or `after`                                                                |
-| Strategy           | `lazy\|eager`, `strategy(-\|=)(lazy\|eager\|defer\|async)`  | Controls the loading strategy. Lazy and eager have shorthand while the remaining values must be prefixed with `strategy`                                 |
-| Fetch Priority     | `fetchpriority(-\|=)(low\|high\|auto)`                      | Controls the fetchpriority property; `auto` is the default                                                                                               |
-| In Footer          | `in-footer`, `in_footer`                                    | Sets the `in_footer` value to `true`; incompatible with `in-header`                                                                                      |
-| In Header          | `in-header`, `in_header`                                    | Sets the `in_footer` value to `false`; incompatible with `in-footer`                                                                                     |
-| Extension          | `([ps]?c\|sa)ss`, `m?[jt]sx?`                               | This determines the type unless it is overridden. This **MUST** be the last token in the name (it is the file extension)                                 |
+| Name                | Token                                                       | Usage                                                                                                                                                    |
+|---------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Enqueuing Location  | `(enqueuing-location)[(-\|=)priority]`                      | This is a special section that is actually a collection of values. See the [Enqueuing Location](#enqueuing-location) section for more details            |
+| Type Override       | `script`, `style`, `script-module`                          | Can be used to override the detected of the asset. Must be the first token in the filename; if used directly, it is shorthand for `both-(Type Override)` |
+| Inline              | `inline[(-\|=)position]`, `strategy(-\|=)inline[-position]` | Indicates that the script should be inlined. `position` can be either `before` or `after`                                                                |
+| Strategy            | `lazy\|eager`, `strategy(-\|=)(lazy\|eager\|defer\|async)`  | Controls the loading strategy. Lazy and eager have shorthand while the remaining values must be prefixed with `strategy`                                 |
+| Fetch Priority      | `fetchpriority(-\|=)(low\|high\|auto)`                      | Controls the fetchpriority property; `auto` is the default                                                                                               |
+| In Footer           | `in-footer`, `in_footer`                                    | Sets the `in_footer` value to `true`; incompatible with `in-header`                                                                                      |
+| In Header           | `in-header`, `in_header`                                    | Sets the `in_footer` value to `false`; incompatible with `in-footer`                                                                                     |
+| Extension           | `([ps]?c\|sa)ss`, `m?[jt]sx?`                               | This determines the type unless it is overridden. This **MUST** be the last token in the name (it is the file extension)                                 |
+| Example Code Marker | `example`                                                   | This informs the build system that the file contains example code and, therefore, should not be build                                                    |
 
 ### Enqueuing Location
 If this is the first token, it can be suffixed with `-script`, `-style`, or `-script-module` to override the type.

package/dist/plugins/ExtensionsConfigFileGeneratorPlugin.js

@@ -52,7 +52,7 @@ class ExtensionsConfigFileGeneratorPlugin extends AbstractBiPhasicGroupAndEntryP
             compilation.contextDependencies.add(srcRoot);
         }
         for await (const dirent of await (0, promises_1.opendir)(srcRoot)) {
-            if (dirent.name.startsWith("~")) {
+            if ((0, shared_1.shouldBeSkipped)(dirent.name)) {
                 continue;
             }
             if (dirent.isFile()) {

package/dist/shared.d.ts

@@ -278,3 +278,7 @@ export declare function synchronousDirIterator(dirPath: string): Generator<impor
  * @link https://dev.to/jdbar
  */
 export declare function instanceOfNodeError<T extends new (...args: any) => Error>(value: unknown, errorType: T): value is InstanceType<T> & NodeJS.ErrnoException;
+/**
+ * This tests if the name starts with a "~", is equal to "example" or "examples", or includes "example" as a name segment
+ */
+export declare function shouldBeSkipped(name: string): boolean;

package/dist/shared.js

@@ -55,6 +55,7 @@ exports.appendAddInlineAssetCall = appendAddInlineAssetCall;
 exports.wrapInlineAssetContents = wrapInlineAssetContents;
 exports.synchronousDirIterator = synchronousDirIterator;
 exports.instanceOfNodeError = instanceOfNodeError;
+exports.shouldBeSkipped = shouldBeSkipped;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
@@ -432,3 +433,9 @@ function* synchronousDirIterator(dirPath) {
 function instanceOfNodeError(value, errorType) {
     return !!value && value instanceof errorType;
 }
+/**
+ * This tests if the name starts with a "~", is equal to "example" or "examples", or includes "example" as a name segment
+ */
+function shouldBeSkipped(name) {
+    return name.startsWith("~") || name === "example" || name === "examples" || name.startsWith("example.") || name.includes(".example.");
+}

package/dist/utils/common-config-helpers.js

@@ -126,7 +126,7 @@ function resolveEntryFromDirectory(commonConfig, srcRoot, dest) {
         const seenExplicitHandles = { scriptHandles: {}, styleHandles: {}, scriptModuleHandles: {} };
         const loadingEntrypoints = [];
         for await (const dirent of await (0, promises_1.opendir)(srcRoot)) {
-            if (!dirent.isDirectory() || dirent.name.startsWith("~")) {
+            if (!dirent.isDirectory() || (0, shared_1.shouldBeSkipped)(dirent.name)) {
                 continue;
             }
             const dir = joinPossiblyAbsolutePaths(srcRoot, dirent.name);

package/dist/utils/location-encoding-filename-parser.js

@@ -7,7 +7,7 @@ const node_path_1 = require("node:path");
 const shared_1 = require("../shared");
 function parseLocationEncodingFilename(filename) {
     const { name, ext } = (0, node_path_1.parse)(filename);
-    if (name.startsWith("~")) {
+    if ((0, shared_1.shouldBeSkipped)(name)) {
         return undefined;
     }
     let type = /^\.(?:s[ac]|p?c)ss$/i.test(ext) ? 'style' : /^\.m[jt]sx?/i.test(ext) ? 'script-module' : /^\.[jt]sx?/i.test(ext) ? 'script' : false;

package/dist/wordpress-scripts-wrapper.js

@@ -511,7 +511,7 @@ function processIndividualWebpackConfig(config, webpackConfig, sources, canClean
                 const entry = async () => {
                     const rawEntrypoints = [];
                     for await (const dirent of await (0, promises_1.opendir)(srcRoot)) {
-                        if (dirent.name.startsWith("~")) {
+                        if ((0, shared_1.shouldBeSkipped)(dirent.name)) {
                             continue;
                         }
                         if (dirent.isFile()) {
@@ -579,7 +579,7 @@ function processIndividualWebpackConfig(config, webpackConfig, sources, canClean
 async function walkExtensionsTree(srcRoot, dest, applicableExtensionTest, parents) {
     const res = [];
     for await (const dirent of await (0, promises_1.opendir)(srcRoot)) {
-        if (dirent.name.startsWith("~")) {
+        if ((0, shared_1.shouldBeSkipped)(dirent.name)) {
             continue;
         }
         if (dirent.isFile()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaudit/webpack-extensions",
-  "version": "3.15.1",
+  "version": "3.16.0",
   "license": "SEE LICENSE IN LICENSE.md",
   "files": [
     "/dist",