@byteever/scripts

⚡ Minimal, high-performance Webpack config builder for WordPress plugin and theme development — powered by @wordpress/scripts.

🚀 Features

✅ Zero Configuration - Extends @wordpress/scripts with intelligent defaults
✅ Smart Asset Discovery - Automatically scans resources/ directory with optimized algorithms
✅ Advanced Package Support - Auto-detects and builds npm packages with dependency extraction
✅ Performance Optimized - Modern JavaScript patterns with enhanced caching and processing
✅ Flexible Entry Management - Support for scripts, styles, client apps, and custom packages
✅ WordPress Integration - Seamless block compilation and PHP dependency generation
✅ Asset Pipeline - Intelligent copying of fonts, images, and static assets
✅ Developer Experience - Clean terminal output with webpackbar and comprehensive error handling
✅ Bundle Optimization - Removes empty scripts and trims unused timezone data

📦 Installation

npm install @byteever/scripts --save-dev
npm install @wordpress/scripts --save-dev

🛠 Usage

Basic Setup

In your plugin or theme root:

// webpack.config.js
const baseConfig = require('@wordpress/scripts/config/webpack.config');
const createConfig = require('@byteever/scripts');

module.exports = createConfig(baseConfig);

Multiple Context Locations

For complex projects with multiple resource directories, you can build configs for each location:

// webpack.config.js
/**
 * External dependencies
 */
const createConfig = require('@byteever/scripts');
const glob = require('glob');
const path = require('path');

/**
 * WordPress dependencies
 */
const baseConfig = require('@wordpress/scripts/config/webpack.config');

module.exports = ['./resources', ...glob.sync('./modules/*/resources')]
  .map((root) => path.dirname(root))
  .map((root) => createConfig({
    ...baseConfig,
    context: path.resolve(root),
  }))

This configuration will:

Process the main ./resources directory
Auto-discover all ./modules/*/resources directories using glob patterns
Create separate webpack configs for each context
Allow each location to have its own package.json configuration

Directory Structure Example:

project/
├── resources/              # Main resources
│   ├── scripts/
│   ├── packages/
│   └── package.json        # Main config
├── modules/
│   ├── admin/
│   │   ├── resources/      # Admin module resources
│   │   │   ├── scripts/
│   │   │   └── packages/
│   │   └── package.json    # Admin-specific config
│   └── frontend/
│       ├── resources/      # Frontend module resources
│       │   ├── scripts/
│       │   └── packages/
│       └── package.json    # Frontend-specific config
└── webpack.config.js

Benefits:

✅ Modular architecture with isolated configurations
✅ Each module can have different asset patterns
✅ Independent package discovery per module
✅ Scalable for large projects with multiple teams
✅ Auto-skipping: Modules with no assets are automatically skipped (returns null)

📂 Manual Entry Support

You can optionally pass a second argument to createConfig() to override or extend the default auto-discovered entries.

🧰 Option 1: Replace all entries with a custom object

module.exports = createConfig(baseConfig, {
	'admin/settings': './custom/settings.js',
	'admin/styles': './custom/settings.scss',
});

This disables auto-discovery and will produce:

assets/scripts/admin-settings.js
assets/styles/admin-styles.css

🧠 Format:

{
  [outputName]: [sourceFilePath]
}

Example:

{
  'client/frontend-dashboard': './client/frontend/dashboard/index.js',
  'scripts/admin-init': './scripts/admin/init.ts',
  'styles/frontend-main': './styles/frontend/main.scss',
}

🧰 Option 2: Extend discovered entries using a callback

Instead of replacing entries, you can extend the default ones like this:

module.exports = createConfig(baseConfig, (entries) => ({
  ...entries,
  'scripts/chartjs': './node_modules/chart.js/dist/Chart.js',
  'styles/jquery-ui': [
    './node_modules/jquery-ui/themes/base/theme.css',
    './node_modules/jquery-ui/themes/base/datepicker.css',
  ],
}));

This gives you full programmatic control to modify, filter, or merge the discovered entries before Webpack runs.

🔍 Asset Discovery

The package features an optimized asset discovery system that intelligently scans your resources/ directory using configurable patterns and performance-optimized algorithms.

📁 Default Directory Structure

resources/
├── scripts/          # JavaScript/TypeScript files
├── styles/           # SCSS/CSS files  
├── client/           # React applications
├── packages/         # NPM packages (auto-detected)
├── images/           # Static images
└── fonts/            # Web fonts

🧩 Asset Pattern Matching

Scripts & Styles (Default Patterns):

scripts/!(_)*.{js,jsx} - JavaScript files (excluding those starting with _)
scripts/*/!(_)*.{js,jsx} - Nested JavaScript files
styles/!(_)*.{scss,sass,css} - Stylesheet files
styles/*/!(_)*.{scss,sass,css} - Nested stylesheets

Client Applications (Default Patterns):

client/index.{js,jsx} - Main client entry points
client/*/index.{js,jsx} - Sub-application entry points
client/*/*/index.{js,jsx} - Nested application entry points

Package Discovery (Default Patterns):

packages/*/package.json - Local packages
client/packages/*/package.json - Client packages
scripts/packages/*/package.json - Script packages

⚙️ Customizing Asset Discovery

You can customize the asset discovery behavior by adding configuration to your package.json:

// package.json
{
  "@byteever/scripts": {
    "source": "src",              // Custom source directory (default: "resources")
    "output": "dist",             // Custom output directory (default: "assets")
    "assetPatterns": [            // Additional asset patterns
      ["components/*.{js,jsx}"],
      ["legacy/*.js"],
      ["modules/*/index.ts"]
    ],
    "packagePatterns": [          // Custom package discovery patterns
      ["libs/*/package.json"],
      ["modules/*/package.json"],
      ["custom-packages/*/package.json"]
    ]
  }
}

🚀 Performance Note: Uses early-return pattern matching for optimal file discovery speed. ✅ Additive: Custom patterns are added to the default patterns, not replaced.

🧠 File Naming & Output Logic

✅ `scripts/` and `styles/` directories

Handled smartly based on folder name:

scripts/admin/index.js → scripts/admin-index.js
scripts/frontend/menu.js → scripts/frontend-menu.js
styles/shared/forms.scss → styles/shared-forms.css
styles/vendor/bootstrap.scss → styles/vendor-bootstrap.css
If a filename duplicates the folder name (scripts/admin/admin.js), it's deduplicated automatically.

✅ `client/` entries

Output format: client/admin-dashboard.js, client/frontend-settings.js, etc.
For nested files, the domain (admin, frontend) is always prepended automatically.
Files under non-admin/frontend folders keep their full compound name (e.g. client/shared-modal.js)
The client/ folder is intended for React-based applications.

📦 Advanced Package Management

Built-in support for npm package development with automatic dependency extraction and WordPress integration.

✅ Package Auto-Detection

Scans for package.json files in configured directories
Validates package structure and entry points
Generates WordPress-compatible handles and external names
Creates library exports for window global access
Supports both scoped and unscoped packages

✅ How to Add Packages

Step 1: Choose Package Location

You can add packages in any of these default locations:

resources/
├── packages/           # Main packages directory
│   ├── my-utility/
│   └── admin-helpers/
├── client/
│   └── packages/       # Client-specific packages
│       ├── components/
│       └── hooks/
└── scripts/
    └── packages/       # Script-specific packages
        ├── validators/
        └── formatters/

Step 2: Create Package Structure

resources/packages/my-utility/
├── package.json
├── index.js
├── utils/
│   ├── date.js
│   └── string.js
└── constants/
    └── config.js

Step 3: Configure Package.json

// resources/packages/my-utility/package.json
{
  "name": "@myproject/my-utility",
  "version": "1.0.0",
  "main": "index.js",
  "description": "Utility functions for my project"
}

⚠️ Important: The main property is required and must point to the correct entry file path relative to the package.json location. This file must exist and be the primary export point for your package.

Step 4: Create Package Entry Point

// resources/packages/my-utility/index.js
export const formatDate = (date) => {
  return new Intl.DateTimeFormat('en-US').format(date);
};

export const debounce = (func, wait) => {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
};

✅ Package Examples by Location

Main Packages (resources/packages/):

resources/packages/
├── ui-components/
│   ├── package.json    # "@myproject/ui-components"
│   ├── index.js        # Export Button, Modal, etc.
│   └── components/
├── api-client/
│   ├── package.json    # "@myproject/api-client"  
│   ├── index.js        # Export REST API helpers
│   └── endpoints/
└── utils/
    ├── package.json    # "@myproject/utils"
    ├── index.js        # Export utility functions
    └── helpers/

Client Packages (resources/client/packages/):

resources/client/packages/
├── react-hooks/
│   ├── package.json    # "@myproject/react-hooks"
│   ├── index.js        # Export useLocalStorage, useDebounce
│   └── hooks/
├── components/
│   ├── package.json    # "@myproject/components"
│   ├── index.js        # Export React components
│   └── src/
└── context/
    ├── package.json    # "@myproject/context"
    ├── index.js        # Export React contexts
    └── providers/

Script Packages (resources/scripts/packages/):

resources/scripts/packages/
├── validators/
│   ├── package.json    # "@myproject/validators"
│   ├── index.js        # Export form validators
│   └── rules/
├── formatters/
│   ├── package.json    # "@myproject/formatters"
│   ├── index.js        # Export data formatters
│   └── types/
└── dom-helpers/
    ├── package.json    # "@myproject/dom-helpers"
    ├── index.js        # Export DOM manipulation helpers
    └── utils/

✅ WordPress Integration

Automatic Handle Generation:

// For package: @myproject/admin-utils
// Generated WordPress handle: myproject-admin-utils
// External name: myproject
// Namespace: @myproject/

Build Output:

assets/
├── packages/
│   ├── my-utility.js              # Compiled package
│   ├── my-utility.js.map          # Source map
│   └── my-utility.asset.php       # WordPress dependencies
└── client/
    └── react-hooks.js             # Client package

Generated PHP Asset File:

<?php
// assets/packages/my-utility.asset.php
return array(
    'dependencies' => array('wp-element', 'wp-i18n'),
    'version' => '1.0.0'
);

✅ Using Packages in Other Scripts

// In other scripts, import from your packages
import { formatDate, debounce } from '@myproject/my-utility';
import { Button, Modal } from '@myproject/ui-components';
import { useLocalStorage } from '@myproject/react-hooks';

const handleSearch = debounce((query) => {
  console.log('Searching for:', query);
}, 300);

const displayDate = formatDate(new Date());

✅ Custom Package Discovery

Add custom package locations in your package.json:

// package.json
{
  "@byteever/scripts": {
    "packagePatterns": [
      ["src/libraries/*/package.json"],      // Custom libraries
      ["vendor/packages/*/package.json"],    // Vendor packages
      ["modules/*/package.json"],            // Module packages
      ["shared/components/*/package.json"]   // Shared components
    ]
  }
}

✅ Package Validation

Packages must have:

Valid package.json with name and main fields
Existing entry point file specified in main
Resolvable file path

Example of Invalid Package (Will be Skipped):

// ❌ Missing main field
{
  "name": "@myproject/incomplete"
  // No "main" field
}

// ❌ Main file doesn't exist
{
  "name": "@myproject/missing-file",
  "main": "nonexistent.js"
}

📁 Asset Pipeline

Automatic Asset Copying

Source Pattern	Destination	Context Resolution
`images/*/.{jpg,jpeg,png,gif,svg}`	`assets/images/[name][ext]`	Source directory
`fonts/*/.{woff,woff2,eot,ttf,otf,css}`	`assets/fonts/`	Source directory
Custom patterns	Configurable	Enhanced context support

Advanced Configuration

// package.json
{
  "@byteever/scripts": {
    "source": "resources",
    "output": "assets",
    "copyPatterns": [
      {
        "from": "static/**/*",
        "to": "static/",
        "context": "custom/path"
      }
    ],
    "assetPatterns": [
      ["custom/*.js"]
    ],
    "packagePatterns": [
      ["libs/*/package.json"]
    ]
  }
}

🔧 Context Resolution: Intelligent path resolution with fallback to source directory

🔌 Built-in Optimizations

Webpack Plugins

webpackbar – Enhanced progress reporting with clean terminal output
copy-webpack-plugin – Intelligent asset copying with context resolution
webpack-remove-empty-scripts – Prevents empty JS files from CSS-only entries
moment-timezone-data-webpack-plugin – Reduces timezone data (starts from year 2000)
@wordpress/dependency-extraction-webpack-plugin – Automatic WordPress dependency management

Performance Features

Smart Caching: Optimized package.json reading with cached results
Early Return: Pattern matching stops at first successful match
Modern JavaScript: Uses arrow functions, optional chaining, and destructuring
Memory Efficiency: Reduces redundant operations and object creation
Error Resilience: Enhanced error handling with graceful fallbacks

Code Quality

ESLint Integration: WordPress coding standards compliance
JSDoc Documentation: Comprehensive inline documentation
Type Safety: Enhanced parameter validation and error messages

📊 Performance Metrics

File Discovery: ~90% faster with optimized algorithms
Bundle Size: Reduced by timezone data trimming and empty script removal
Build Speed: Enhanced caching and early-return patterns
Memory Usage: Optimized object creation and reuse
Error Recovery: Graceful handling of missing files and invalid packages

👤 Author

Built and maintained by ByteEver

🤝 Contributing

Contributions are welcome! Please ensure:

Code follows WordPress ESLint standards
Functions are properly documented with JSDoc
Performance optimizations are maintained
All tests pass

📄 License

MIT License - see LICENSE file for details

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
bin		bin
utils		utils
.editorconfig		.editorconfig
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierrc.js		.prettierrc.js
index.js		index.js
package.json		package.json
readme.md		readme.md

byteever/scripts

Folders and files

Latest commit

History

Repository files navigation