wp-react-plugin-cli

🚀 The fastest way to create WordPress plugins with React components

A CLI tool that scaffolds complete WordPress plugins with React, TypeScript, and Redux integration in under 30 seconds. Build modern WordPress plugins using the development tools you already know and love.

✨ Why This Exists

WordPress developers have been stuck with PHP and jQuery while the JavaScript world moved to React, TypeScript, and modern tooling. JavaScript developers have been locked out of WordPress's massive ecosystem.

This changes everything.

Build WordPress plugins with:

• ⚡ React components that render via shortcodes
• 🛡️ TypeScript for better development experience
• 🎯 Self-registering components - no manual setup needed
• 🔧 Modern tooling - Webpack, hot reload, proper build pipeline
• 🔌 WordPress integration - authentication, REST API, nonces built-in

🚀 Quick Start

# Create your plugin in 30 seconds
npx wp-react-plugin-cli my-awesome-plugin

# Copy to WordPress
cp -r my-awesome-plugin /path/to/wp-content/plugins/

# Start development  
cd /path/to/wp-content/plugins/my-awesome-plugin
npm run dev

# Activate plugin and use shortcodes!
[my-awesome-plugin page="hello_world"]

That's it! You now have a working WordPress plugin with React components.

📦 What You Get

Self-Registering Components

No more manual component registration. Just export your component with a pageName:

// src/components/ProductGrid.tsx
export const ProductGrid = ({ category }) => {
  return <div>Your React component here</div>;
};

// This makes it accessible via shortcode
ProductGrid.pageName = 'product_grid';

Use anywhere in WordPress:

[my-plugin page="product_grid" category="electronics"]

Complete Development Environment

• 🔧 Webpack configured for WordPress
• 📝 TypeScript with proper WordPress types
• 🎨 Hot reload during development
• ✅ ESLint for code quality
• 📚 Comprehensive documentation

WordPress Integration That Just Works

export const UserDashboard = ({ wpSettings }) => {
  // Access WordPress user data
  const { user_id, is_user_logged_in } = wpSettings;
  
  if (!is_user_logged_in) {
    return <div>Please log in to continue</div>;
  }

  // Make authenticated API calls
  const fetchUserPosts = () => {
    return fetch(`/wp-json/wp/v2/posts?author=${user_id}`, {
      headers: { 'X-WP-Nonce': wpSettings.nonce }
    });
  };

  return <div>Welcome back, User #{user_id}!</div>;
};

UserDashboard.pageName = 'user_dashboard';

🎯 CLI Options

# Interactive mode (recommended)
npx wp-react-plugin-cli

# Quick mode with defaults
npx wp-react-plugin-cli my-plugin --yes

# Specify author info
npx wp-react-plugin-cli my-plugin \
  --author "Your Name" \
  --email "[email protected]"

# Skip installation steps
npx wp-react-plugin-cli my-plugin --skip-install --skip-build

Available Templates

Basic Template

• HelloWorld component
• WordPress integration basics
• Perfect for simple plugins

Advanced Template

• Multiple example components
• User authentication examples
• Contact forms and data tables
• Full WordPress feature integration

E-commerce Template

• WooCommerce integration
• Product display components
• Shopping cart examples
• Order management

📁 Generated Plugin Structure

my-awesome-plugin/
├── my-awesome-plugin.php     # WordPress plugin file
├── src/
│   ├── index.tsx            # Auto-discovers components
│   └── components/          # Your React components
│       ├── HelloWorld.tsx   # Example component
│       └── UserDashboard.tsx
├── build/
│   └── index.js            # Compiled JavaScript
├── package.json            # Dependencies & scripts
├── webpack.config.js       # Build configuration
└── tsconfig.json          # TypeScript configuration

🛠️ Development Workflow

1. Generate Plugin

npx wp-react-plugin-cli my-plugin

2. Move to WordPress

cp -r my-plugin /path/to/wp-content/plugins/

3. Start Development

cd /path/to/wp-content/plugins/my-plugin
npm run dev  # Watches files and rebuilds automatically

4. Activate & Use

1. Activate plugin in WordPress admin
2. Add shortcode to any page: [my-plugin page="hello_world"]
3. Edit components in src/components/ - changes auto-rebuild

5. Deploy

npm run build  # Production build
# Upload plugin folder to production (including build/index.js)

🎨 Adding New Components

Create a new file in src/components/:

// src/components/NewsletterSignup.tsx
import React, { useState } from 'react';

interface NewsletterSignupProps {
  title?: string;
  wpSettings?: any;
}

export const NewsletterSignup: React.FC<NewsletterSignupProps> = ({ 
  title = "Subscribe to Newsletter",
  wpSettings 
}) => {
  const [email, setEmail] = useState('');
  const [status, setStatus] = useState('');

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    const response = await fetch('/wp-json/my-plugin/v1/newsletter', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-WP-Nonce': wpSettings?.nonce
      },
      body: JSON.stringify({ email })
    });

    if (response.ok) {
      setStatus('Thanks for subscribing!');
      setEmail('');
    } else {
      setStatus('Something went wrong. Please try again.');
    }
  };

  return (
    <div style={{ padding: '20px', background: '#f9f9f9', borderRadius: '8px' }}>
      <h3>{title}</h3>
      <form onSubmit={handleSubmit}>
        <input
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          placeholder="Enter your email"
          required
          style={{ padding: '10px', marginRight: '10px', borderRadius: '4px' }}
        />
        <button 
          type="submit"
          style={{ padding: '10px 20px', borderRadius: '4px', border: 'none', background: '#0073aa', color: 'white' }}
        >
          Subscribe
        </button>
      </form>
      {status && <p style={{ marginTop: '10px' }}>{status}</p>}
    </div>
  );
};

// Make it accessible via shortcode
NewsletterSignup.pageName = 'newsletter_signup';

That's it! No imports, no registration, no configuration needed.

Use it anywhere in WordPress:

[my-plugin page="newsletter_signup" title="Join Our Newsletter"]

🌟 Real-World Examples

Product Catalog

export const ProductCatalog = ({ category = 'all', limit = '12' }) => {
  const [products, setProducts] = useState([]);
  
  useEffect(() => {
    fetch(`/wp-json/wc/v3/products?category=${category}&per_page=${limit}`)
      .then(res => res.json())
      .then(setProducts);
  }, [category, limit]);

  return (
    <div className="product-grid">
      {products.map(product => (
        <div key={product.id} className="product-card">
          <img src={product.images[0]?.src} alt={product.name} />
          <h3>{product.name}</h3>
          <p dangerouslySetInnerHTML={{ __html: product.price_html }} />
        </div>
      ))}
    </div>
  );
};

ProductCatalog.pageName = 'product_catalog';

Usage: [my-plugin page="product_catalog" category="electronics" limit="8"]

User Profile

export const UserProfile = ({ wpSettings }) => {
  const [profile, setProfile] = useState(null);

  useEffect(() => {
    if (wpSettings?.is_user_logged_in) {
      fetch('/wp-json/wp/v2/users/me', {
        headers: { 'X-WP-Nonce': wpSettings.nonce }
      })
      .then(res => res.json())
      .then(setProfile);
    }
  }, [wpSettings]);

  if (!wpSettings?.is_user_logged_in) {
    return <a href="/wp-login.php">Please log in</a>;
  }

  return (
    <div>
      <h2>Welcome, {profile?.name}!</h2>
      <p>Email: {profile?.email}</p>
      <p>Member since: {new Date(profile?.registered_date).toLocaleDateString()}</p>
    </div>
  );
};

UserProfile.pageName = 'user_profile';

🔧 Available Scripts

npm run dev          # Development mode with file watching
npm run build        # Production build (minified)
npm run type-check   # TypeScript type checking
npm run lint         # Code linting

🚀 Why This Is Game-Changing

For JavaScript Developers

• Build WordPress plugins without learning PHP
• Use React, TypeScript, and modern tooling you already know
• Access WordPress's massive ecosystem and hosting options

For WordPress Developers

• Leverage the entire React ecosystem
• Modern development experience with hot reload and TypeScript
• Component-based architecture instead of spaghetti PHP

For Agencies & Freelancers

• Faster development cycles
• Modern codebase that's easier to maintain
• Access to both WordPress and React talent pools

📚 Complete Documentation

| Guide | Description | |-------|-------------| | 📖 Usage Guide | Complete usage instructions, examples, and troubleshooting | | 🛠️ Developer Guide | Architecture, advanced patterns, and contributing | | 🔌 WordPress Integration | Deep dive into WordPress/React bridge |

💡 New to WordPress + React? Start with the Usage Guide

🔍 Troubleshooting

Components Not Showing

# Check if plugin is activated in WordPress admin
# Verify shortcode syntax: [plugin-name page="component_name"]
# Check browser console for JavaScript errors

Build Issues

# Clear cache and rebuild
rm -rf node_modules build package-lock.json
npm install
npm run build

TypeScript Errors

# Check types
npm run type-check

# Make sure component has proper TypeScript interface
interface MyComponentProps {
  myProp?: string;
  wpSettings?: any;
}

🏗️ How It Works

1. CLI generates complete WordPress plugin with React integration
2. PHP plugin registers shortcodes and enqueues JavaScript
3. Shortcodes create containers for React components
4. JavaScript auto-discovers components with pageName and mounts them
5. Components receive shortcode attributes as props + WordPress context

This bridges WordPress (PHP) and React (JavaScript) seamlessly.

🤝 Contributing

Found a bug? Have a feature idea? Contributions welcome!

git clone https://github.com/shawnk45/wp-react-plugin-cli
cd wp-react-plugin-cli
npm install
npm run build
npm link

# Test your changes
wp-react-plugin-cli test-plugin

📄 License

MIT License - build awesome things!

Ready to revolutionize WordPress development?

npx wp-react-plugin-cli my-awesome-plugin

From zero to WordPress + React plugin in 30 seconds. 🚀

No PHP knowledge required. No WordPress boilerplate. Just modern JavaScript development that works with WordPress.