wp-recache/docs/plans/2026-09-13-wprecache-design.md

WP Recache — Open Source Performance Plugin

Overview

Create a commercial-grade WordPress performance plugin with feature parity to WP Rocket, implemented via clean-room methodology. The plugin will be open source (GPL-2.0+) and provide page caching, file optimization, and image optimization.

Clean-Room Methodology

Rules

1. No code reuse. Never copy, paste, or adapt any PHP/JS/CSS from WP Rocket.
2. Feature specs only. Document what WP Rocket does from a user perspective (UI behavior, options, output), not how it's implemented.
3. Independent implementation. All code written from scratch using WordPress APIs and standard libraries.
4. Documentation trail. Keep records of the specification process to prove independent development.

What We Study (User Perspective)

• WP Rocket admin UI: what settings exist, what they control
• Frontend output: what HTML/JS/CSS changes appear after activation
• Behavior: when cache clears, what gets optimized, what's excluded by default
• Performance: what metrics improve

What We Ignore

• PHP source code structure
• Internal class/function naming
• Specific implementation patterns
• Hook naming conventions

Feature Specifications

1. Page Cache

User-facing behavior:

• On first anonymous visit, generates static HTML file
• Subsequent anonymous visits serve the static file directly
• Cache auto-purges when content is published/updated
• Manual purge available from admin bar and settings page
• Excludes logged-in users, cart/checkout pages, specific URLs
• Separate cache for mobile devices (optional)
• Preload/crawl sitemap to warm cache

Technical approach (independent implementation):

• Use WordPress advanced-cache.php drop-in
• Output buffering via ob_start() / ob_get_contents() / ob_end_flush()
• Cache files stored in wp-content/cache/
• Serve cached files via direct file read before WordPress loads
• Use WordPress rewrite rules for cache detection

2. File Optimization — CSS

User-facing behavior:

• Minify CSS files (remove whitespace, comments)
• Combine CSS files into fewer requests
• Defer non-critical CSS loading
• Remove unused CSS (RUCSS — Remove Unused CSS)
• Inline critical CSS for above-the-fold content
• Async CSS loading

Technical approach:

• Use CSS minification library (e.g., natanielrodman/css-minify or similar)
• Parse CSS to identify critical path selectors
• Output buffering to detect and modify <link> tags
• Generate critical CSS via headless browser or parser

3. File Optimization — JavaScript

User-facing behavior:

• Minify JavaScript files
• Combine JavaScript files
• Defer JavaScript loading (load after HTML parsed)
• Delay JavaScript execution (load on user interaction)
• Remove jQuery Migrate
• Delay inline scripts

Technical approach:

• Use JavaScript minification (e.g., tedivm/jshrink or similar)
• Output buffering to modify <script> tags
• Add defer or async attributes
• Wrap scripts in event listeners for delay functionality

4. Image Optimization

User-facing behavior:

• Lazy load images (load when entering viewport)
• Convert images to WebP/AVIF format
• Optimize image compression
• Add missing width/height attributes (CLS prevention)
• Placeholder images while loading

Technical approach:

• Use loading="lazy" attribute (native lazy loading)
• Use WordPress wp_image_editor APIs for format conversion
• Use Imagick/GD for compression
• Generate WebP/AVIF variants on upload

5. Additional Features

Critical CSS:

• Generate critical CSS for above-the-fold content
• Inline critical CSS, defer full stylesheet
• Per-page critical CSS generation

Preload:

• Preload key requests (fonts, critical resources)
• DNS prefetch for external domains
• Prefetch for likely next pages

Database Optimization:

• Clean post revisions
• Clean auto-drafts
• Clean trashed posts
• Optimize database tables

Architecture

Plugin Structure

wp-recache/
├── wp-recache.php                 # Main plugin file
├── uninstall.php                  # Clean uninstall
├── composer.json                  # Dependencies
├── readme.txt                     # WordPress.org readme
├── assets/
│   ├── css/
│   │   └── admin.css              # Admin UI styles
│   └── js/
│       └── admin.js               # Admin UI scripts
├── includes/
│   ├── Activator.php              # Plugin activation
│   ├── Deactivator.php            # Plugin deactivation
│   ├── Plugin.php                 # Main plugin class
│   ├── Admin/
│   │   ├── Admin.php              # Admin functionality
│   │   ├── Settings.php           # Settings page
│   │   └── Assets.php             # Admin assets
│   ├── Cache/
│   │   ├── WPCache.php            # Core page cache
│   │   ├── Purge.php              # Cache purge logic
│   │   └── Preloader.php          # Cache preloading
│   ├── Optimization/
│   │   ├── CSS/
│   │   │   ├── Minify.php         # CSS minification
│   │   │   ├── Combine.php        # CSS combination
│   │   │   └── CriticalCSS.php    # Critical CSS generation
│   │   ├── JS/
│   │   │   ├── Minify.php         # JS minification
│   │   │   ├── Combine.php        # JS combination
│   │   │   └── Defer.php          # JS defer/delay
│   │   └── RemoveUnusedCSS.php    # RUCSS
│   ├── Media/
│   │   ├── Lazyload.php           # Image lazy loading
│   │   ├── ImageFormat.php        # WebP/AVIF conversion
│   │   └── ImageOptimize.php      # Image compression
│   ├── Database/
│   │   └── Optimizer.php          # Database cleanup
│   └── Common/
│       ├── FileSystem.php         # File system utilities
│       ├──钩子/钩子.php           # Hook utilities
│       └── HTTP.php               # HTTP utilities
├── views/
│   ├── admin-settings.php         # Settings page template
│   └── admin-bar.php              # Admin bar menu
└── languages/
    └── wp-recache.pot             # Translation template

Key Design Decisions

1. No vendor dependencies for core features. Use WordPress built-in APIs wherever possible.
2. Modular architecture. Each feature (cache, CSS, JS, images) is independent and can be disabled.
3. WordPress standards. Follow WordPress coding standards and hook system.
4. Performance first. Minimal overhead, no unnecessary database queries.

Implementation Strategy

Phase 1: Core Page Cache

• Implement advanced-cache.php drop-in
• Output buffering for HTML generation
• Cache file management (create, serve, purge)
• Admin settings page (basic)
• Admin bar purge button

Phase 2: File Optimization

• CSS minification
• JS minification
• CSS/JS combination
• Defer/delay scripts
• Critical CSS generation

Phase 3: Image Optimization

• Lazy loading
• WebP/AVIF conversion
• Image compression
• CLS prevention (width/height)

Phase 4: Advanced Features

• Remove unused CSS
• Database optimization
• Preloading
• CDN support

Legal Considerations

1. Document everything. Keep records of the specification process.
2. Never access WP Rocket source while implementing.
3. Use different naming. Don't use "rocket" prefixes or similar naming.
4. Independent architecture. Design your own class structure.
5. Different defaults. Choose different default settings where possible.

Open Source Strategy

1. License: GPL-2.0-or-later (same as WordPress)
2. Repository: GitHub with public access
3. WordPress.org: Submit to plugin directory
4. Community: Accept contributions, maintain active development
5. Commercial model: Open core with premium features or SaaS add-ons

Success Criteria

1. Feature parity with WP Rocket for page cache, file optimization, image optimization
2. No code overlap (verified by code review)
3. Performance benchmarks comparable to or better than WP Rocket
4. Clean, maintainable code following WordPress standards
5. Active open source community