@pugpigjs/vite-wp-config

Shared Vite configuration and plugins for building WordPress themes and plugins.

Installation

npm install --save-dev @pugpigjs/vite-wp-config

Peer Dependencies

This package requires the following peer dependencies:

npm install --save-dev @vitejs/plugin-vue git-describe glob rollup-plugin-copy-watch sass tar vite vue

Usage

Basic Setup

Create a vite.config.js in your theme or plugin directory:

import { createViteConfig } from '@pugpigjs/vite-wp-config'

export default createViteConfig()

Custom Configuration

You can extend the base configuration:

import { createViteConfig } from '@pugpigjs/vite-wp-config'

export default createViteConfig({
  // Add custom Vite options here
  server: {
    port: 3000
  }
})

Or use a function for dynamic configuration:

import { createViteConfig } from '@pugpigjs/vite-wp-config'

export default createViteConfig(({ mode, isProduction }) => ({
  // Custom config based on mode
  define: {
    __APP_VERSION__: JSON.stringify('1.0.0')
  }
}))

Features

Directory Structure

The config expects your WordPress theme/plugin to follow this structure:

your-plugin/
├── src/
│   ├── scripts/
│   │   └── main.js          # Entry point (optional)
│   ├── styles/
│   │   └── _style.sass      # For themes: becomes style.css
│   ├── **/*.php             # PHP files (copied to dist)
│   ├── **/*.mustache        # Template files (copied to dist)
│   ├── composer.json        # Copied to dist, triggers composer delta
│   ├── vendor/              # Copied to dist (once)
│   └── index.php            # Main plugin file
├── public/
│   └── **/*                 # Public assets (copied to dist)
├── dist/
│   └── your-plugin/         # Built output
│       ├── scripts/         # Compiled JavaScript
│       ├── styles/          # Compiled CSS
│       ├── **/*.php         # Copied PHP files
│       ├── composer.json    # Copied composer config
│       ├── vendor/          # PHP dependencies
│       └── dev-server.json  # HMR config (dev mode only)
├── build/
│   ├── your-plugin.tar.gz   # Production archive
│   └── gittag.txt           # Version tag
├── vite.config.js
└── package.json

Automatic Features

1. File Copying & Watching

• PHP files - Copied from src/ to dist/ and watched for changes, triggers composer delta (PHPStan analysis)
• Mustache templates - Copied and watched
• composer.json - Copied to dist/ (contains delta script definition for PHPStan)
• Vendor directory - Copied once on initial build (not watched)
• Public assets - Files from public/ copied to dist/
• Watch mode - Automatically re-copies files on changes (dev/serve modes)

2. Asset Organisation

Built assets are organised into directories:

• scripts/ - JavaScript files
• styles/ - CSS files (except style.css for themes)
• images/ - Image assets
• fonts/ - Font files
• templates/ - Mustache templates
• chunks/ - Code-split chunks

3. WordPress Theme Support

For themes, any file named _style.sass (or _style.css) will be output as style.css in the root (WordPress requirement).

4. Git Version Injection

The string GIT_VERSION in your code is automatically replaced with the git tag:

• Format: {tag} or {tag}_dev (if commits ahead) or {tag}_dev_local (if dirty)
• Works in JS, CSS, PHP, HTML, and TXT files

Example:

/**
 * Plugin Name: My Plugin
 * Version: GIT_VERSION
 */

Becomes:

/**
 * Plugin Name: My Plugin
 * Version: 1.2.3
 */

5. Mix Manifest Generation

Generates a mix-manifest.json for compatibility with Laravel Mix/WordPress projects.

6. Production Packaging

In production builds, automatically creates:

• A .tar.gz archive in dist/build/
• A gittag.txt file with the version

7. Dev Server Configuration File

When running in HMR mode (npm run serve), a dev-server.json file is automatically created in dist/ with the following structure:

{
  "host": "localhost",
  "port": 5173,
  "protocol": "http",
  "base": ""
}

The values are determined from:

• Environment variables (VITE_PUBLIC_* for proxy setups)
• Server configuration (VITE_SERVER_* for direct access)
• Vite's detected server address (fallback)

Build Modes

Development Mode

npm run dev
# or
vite build --watch --mode development

• Watches for changes
• No content hashing in filenames
• Source maps enabled
• Fast rebuilds

Hot Module Replacement (HMR) Mode

npm run serve
# or
vite --host --mode development

• Starts Vite dev server with HMR support
• Instant updates without page reload
• WebSocket-based hot updates
• Creates dev-server.json for backend integration

How it works:

1. The vite-plugin-wp creates a dev-server.json file in dist/ with server configuration
2. Assets are loaded from the dev server instead of dist files
3. Changes to JS/CSS/Vue files trigger instant HMR updates
4. PHP files are automatically copied to dist (requires page refresh)

Configuration via environment variables:

For direct access:

• VITE_SERVER_HOST - Server bind address (default: "0.0.0.0")
• VITE_SERVER_PORT - Server port (default: 5173)

For reverse proxy setups (Traefik, nginx):

• VITE_PUBLIC_HOST - Public hostname (e.g., "express.pugpig-local.com")
• VITE_PUBLIC_PORT - Public port (default: matches server protocol)
• VITE_PUBLIC_BASE - Base path for assets (e.g., "/vite/rich")

Example with Traefik:

export VITE_PUBLIC_HOST=express.pugpig-local.com
export VITE_PUBLIC_PORT=80
export VITE_PUBLIC_BASE=/__vite__/rich

npm run serve

Production Mode

npm run build
# or
vite build

• Minified output
• Content hashing in filenames
• Creates distribution archive
• Injects git version

Plugin Scripts

Add these scripts to your package.json:

{
  "scripts": {
    "dev": "vite build --watch --mode development",
    "serve": "vite --host --mode development",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Script explanations:

• dev - Watch mode for continuous builds without HMR
• serve - Starts Vite dev server with HMR support
• build - Production build with minification and packaging
• preview - Preview production build locally

Composer Delta Integration (PHPStan)

The config includes automatic composer delta support when PHP files change:

import { createViteConfig } from '@pugpigjs/vite-wp-config'
import { createComposerDeltaHandler } from '@pugpigjs/vite-wp-config/vite-plugins/composer-handler'

export default createViteConfig({
  plugins: [
    // ... other plugins
    vitePluginWp({
      onFileChange: createComposerDeltaHandler(import.meta.dirname)
    })
  ]
})

How it works:

• When PHP files are modified, composer delta runs automatically
• composer delta is a script defined in composer.json that typically runs PHPStan for static analysis
• Uses file locking to prevent concurrent executions
• Runs asynchronously without blocking the dev server
• Logs output through Vite's colored logger

This is already configured in the default setup, so PHP code is continuously analysed during development.

Custom Plugins

You can import individual plugins if you need more control:

import { defineConfig } from 'vite'
import { vitePluginWp } from '@pugpigjs/vite-wp-config/vite-plugins/vite-plugin-wp'
import { vitePluginManifest } from '@pugpigjs/vite-wp-config/vite-plugins/vite-plugin-manifest'
import { vitePluginPackage } from '@pugpigjs/vite-wp-config/vite-plugins/vite-plugin-package'
import { replaceString } from '@pugpigjs/vite-wp-config/vite-plugins/vite-plugin-replace'

export default defineConfig({
  // Your custom config with individual plugins
})

Available plugins:

• vitePluginWp - WordPress-specific functionality (file copying, file watching, dev-server.json generation, HMR support, composer.json change callbacks)
• vitePluginManifest - Generates mix-manifest.json for Laravel Mix compatibility
• vitePluginPackage - Creates .tar.gz archives and version files for production
• replaceString - Replaces strings in output files (used for GIT_VERSION injection)
• createComposerDeltaHandler - File change handler that runs composer delta with locking to prevent concurrent executions

Configuration Options

The createViteConfig() function accepts:

• Object: Merged with base config
• Function: ({ mode, isProduction }) => config - receives build context

The base config includes:

• Vue plugin
• WordPress-specific file handling
• Git version replacement
• Production packaging
• Mix manifest generation

License

ISC