Building a WordPress Plugin with React? Use @wordpress/scripts

Recently, I encountered a challenging WordPress development issue while building a plugin with a React-based admin interface. Everything appeared to be functioning correctly until I attempted to implement media uploads, which resulted in JavaScript errors and broken functionality.

The Problem

When building a React-based admin interface for a WordPress plugin, it is normal to face integration challenges between modern JavaScript tooling and WordPress’s script loading system. In my case, attempting to open the WordPress media library resulted in console errors:

Uncaught TypeError: Cannot read properties of undefined (reading 'svgPainter')
load-scripts.php?c=0,1&ver=6.4.2:formatted:2945

This error indicates a fundamental issue with how JavaScript dependencies are being loaded and managed within the WordPress environment.

Understanding the Root Cause

The issue stems from WordPress’s script concatenation system, which attempts to optimize performance by bundling JavaScript files together. While this approach works well for traditional WordPress development, it can create conflicts when using modern build tools like Vite alongside WordPress’s dependency management system.

My initial setup included:

• Vite for building React components
• Manual dependency management in PHP
• Custom workarounds to disable script concatenation
• Multiple patches to address loading order issues

The fundamental problem was that WordPress expects JavaScript dependencies to be loaded in a specific manner. When manually defining dependencies such as ['wp-element', 'wp-i18n'] in PHP, there’s no guarantee that WordPress will load these dependencies in the correct order or that all required scripts will be available when needed.

Adopting WordPress Standards

After extensive debugging and research into WordPress best practices, it became clear that the optimal solution was to align with WordPress’s recommended build toolchain rather than fighting against it.

Step 1: Replacing Vite with @wordpress/scripts

The first step involved replacing the Vite configuration with WordPress’s standardized webpack setup:

// webpack.config.js
const defaultConfig = require("@wordpress/scripts/config/webpack.config");
const path = require("path");

module.exports = {
  ...defaultConfig,
  entry: {
    admin: path.resolve(process.cwd(), "admin/react/src/main.tsx"),
  },
  output: {
    ...defaultConfig.output,
    path: path.resolve(process.cwd(), "admin/react/dist"),
  },
};Code language: JavaScript (javascript)

This configuration leverages WordPress’s pre-configured webpack setup while maintaining the flexibility to specify custom entry points and output directories.

Step 2: Updating Dependencies and Scripts

The package.json required substantial modifications to align with WordPress standards:

{
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build",
    "lint:js": "wp-scripts lint-js"
  },
  "devDependencies": {
    "@wordpress/scripts": "^30.21.0",
    "@wordpress/element": "^6.28.0",
    "@wordpress/i18n": "^6.1.0"
  }
}Code language: JSON / JSON with Comments (json)

Step 3: Automated Dependency Management

The most significant improvement was the automatic generation of dependency information. @wordpress/scripts creates an asset.php file that contains all necessary dependency data:

<?php return array(
  'dependencies' => array('react', 'react-dom', 'react-jsx-runtime', 'wp-element'),
  'version' => 'aeafe55ce756e8b6bf7d'
);Code language: HTML, XML (xml)

This file is then utilized in the PHP enqueue function:

// Before: Manual dependency management
$dependencies = array('wp-element', 'wp-i18n');

// After: Automated dependency resolution
$asset_file = include($asset_file_path);
wp_enqueue_script(
    $this->plugin_name . '-react',
    plugin_dir_url(__FILE__) . 'react/dist/admin.js',
    $asset_file['dependencies'], // Automatically determined
    $asset_file['version'],
    true
);Code language: PHP (php)

Results and Benefits

After implementing these changes and running npm run build, the issues were completely resolved:

• Media uploads function correctly without JavaScript errors
• No console warnings about missing dependencies
• Cleaner, more maintainable codebase
• Full compliance with WordPress development standards

Have you faced similar issues with WordPress plugin development? Let me know in the comments below!