FlxWoo

FlxWoo transforms your WooCommerce checkout into a modern, blazing-fast experience powered by Next.js, without breaking any existing functionality.

Instead of rebuilding checkout logic in JavaScript (and losing critical features), FlxWoo bridges WordPress/WooCommerce with a Next.js rendering engine. Your store keeps using:

• ✅ All payment gateways – Stripe, PayPal, Square, Klarna, local gateways, etc.
• ✅ Shipping methods & rates – All WooCommerce shipping plugins work
• ✅ Coupons & discounts – Smart coupons, dynamic pricing, etc.
• ✅ Tax calculations – WooCommerce Tax, TaxJar, Avalara, etc.
• ✅ Checkout extensions – Order bumps, upsells, custom fields, etc.

Perfect for agencies and developers who want a modern, custom-designed frontend without rewriting critical WooCommerce logic.

How It Works

1. Plugin installed → Detects WooCommerce cart/checkout/thank-you pages
2. Data collected → Aggregates cart, checkout config, and order data from WooCommerce
3. Sent to Next.js → Transmits data to your Next.js renderer via secure REST API
4. HTML returned → Next.js generates custom-designed HTML with Tailwind CSS
5. Graceful fallback → If Next.js unavailable, displays native WooCommerce templates

Key Features

• 🚀 Modern checkout design – Custom Tailwind CSS templates, fully responsive
• 🔒 Secure by default – Strict CSP headers, XSS protection, PII sanitization
• ⚡ Lightning fast – Server-side rendering, optimized payload (30-40% reduction)
• 🔄 Zero breaking changes – All WooCommerce plugins keep working
• 🎨 Professional templates – Conversion-optimized design, enterprise customization available
• 📱 Mobile-optimized – Responsive design, touch-friendly UI
• 🛡️ Production-ready – CORS handling, fallback mechanism, error recovery
• 🔧 Developer-friendly – REST API endpoints, TypeScript types, comprehensive docs
• ⚙️ Admin settings page – Easy configuration via WordPress admin (v2.1.0)
• 🏥 Health monitoring – Real-time system status and connectivity checks (v2.1.0)
• 🛡️ Rate limiting – API abuse protection with GDPR-compliant logging (v2.1.0)
• 📊 Error monitoring – Automatic issue tracking with PII sanitization (v2.1.0)

What’s Included

This Plugin (flx-woo – Open Source):
– REST API endpoints (/wp-json/flx-woo/v1/)
– WooCommerce data aggregation
– Rendering proxy with fallback
– CORS configuration (zero-config for most setups)
– PII sanitization for logs
– MIT License – freely available on WordPress.org

FlxWoo SaaS Renderer (Free During MVP – Closed Source):
– Hosted Next.js rendering service
– Modern cart, checkout, and thank-you pages
– Professional design with Tailwind CSS 4
– Automatic updates and security patches
– 99.9% uptime SLA
– Currently FREE to use – No signup or payment required during MVP phase
– Note: The Next.js renderer is NOT open source and cannot be self-hosted

Requirements

• WordPress 6.0 or higher
• WooCommerce 8.0 or higher
• PHP 8.0 or higher
• FlxWoo SaaS renderer (automatically configured, currently free)

Why FlxWoo?

Most headless WooCommerce setups fail at checkout — payment gateways stop working, shipping calculations break, and coupons disappear. Developers end up rebuilding everything in JavaScript, which is expensive, time-consuming, and error-prone.

FlxWoo solves this by keeping WordPress/WooCommerce in control of business logic while Next.js handles only the presentation layer. You get a modern frontend without the risk.

Privacy

This plugin transmits data to an external service. Here’s what you need to know:

What Data Is Transmitted

When customers visit cart, checkout, or order confirmation pages, FlxWoo transmits the following data to the FlxWoo SaaS rendering service:

Cart Data:
* Product details (name, SKU, price, quantity, images)
* Cart totals (subtotal, tax, shipping, discounts)
* Applied coupons and fees
* Stock status and product variations

Checkout Data:
* Available payment gateways (name and ID only – NO payment credentials)
* Available shipping methods
* Checkout form fields and validation rules
* Customer billing/shipping addresses (if logged in)

Order Confirmation Data:
* Order details (order number, status, totals)
* Ordered items and quantities
* Billing/shipping addresses
* Customer email

Site Metadata:
* Site name and URL
* Currency settings
* Locale and formatting preferences

What Is NOT Transmitted:
* Payment credentials, API keys, or secrets
* Credit card numbers, CVV codes, or payment tokens
* Passwords or authentication tokens
* Any data from pages other than cart/checkout/thank-you

Where Data Is Sent

Data is transmitted via HTTPS to the FlxWoo SaaS rendering service, a third-party service operated by FlxWoo.

Configuration (v2.1.0+):
* Renderer URL is configurable via: WP Admin > WooCommerce > FlxWoo > Settings
* Can also be set via FLX_WOO_RENDERER_URL constant in wp-config.php
* Contact your site administrator for the specific renderer URL configured on your site

Purpose: Generate optimized HTML for cart, checkout, and order confirmation pages

Data Retention: No permanent storage. Data is processed in memory during page rendering (milliseconds) and immediately discarded.

Security: All transmission uses encrypted HTTPS connections with strict CORS policies and Content Security Policy headers.

Error Monitoring (Optional, v2.1.0+):
* The Next.js renderer may send error reports to Sentry.io for debugging and reliability monitoring
* All PII is automatically sanitized before transmission:
– Emails masked as j***@example.com (keeps domain for debugging)
– Phone numbers masked except last 4 digits
– Names, addresses, and sensitive data automatically redacted
– Passwords, tokens, credit cards completely removed
* WordPress plugin does NOT send data to external error monitoring services
* All WordPress logs remain local to your installation

External Service Information

Service Name: FlxWoo SaaS Renderer
Service Provider: FlxWoo (operated by Rickey Gu)
Service Purpose: HTML rendering for WooCommerce pages
Service URL: Configurable via FLX_WOO_RENDERER_URL constant
Privacy Policy: See PRIVACY.md in plugin directory or visit flxwoo.com/privacy

GDPR & Privacy Compliance

Legal Basis: Processing is necessary for contract performance (GDPR Article 6(1)(b)) – rendering the checkout pages you’ve requested.

User Rights:
* Right to Access – Data available through WooCommerce’s data export tools
* Right to Deletion – Use WooCommerce’s built-in data erasure features
* Right to Object – Contact site administrator to disable FlxWoo

No Cookies: FlxWoo does not set any cookies. Standard WooCommerce session cookies remain in use.

PII Protection: Development logs automatically sanitize personally identifiable information (emails, phone numbers, IP addresses).

Your Responsibilities

As a site owner using this plugin:

1. Update Your Privacy Policy: Inform customers that cart/checkout data is transmitted to FlxWoo’s rendering service
2. Obtain Consent: Ensure your privacy policy covers this data transmission (required in some jurisdictions)
3. Keep Updated: Regularly update WordPress, WooCommerce, and FlxWoo for security patches

Suggested Privacy Policy Text:

Our website uses FlxWoo to provide an optimized checkout experience. When you view your cart or checkout, your cart data and product selections are temporarily transmitted to FlxWoo’s rendering service via encrypted HTTPS connection. This data is processed in real-time and is not permanently stored.

More Information

For complete privacy details, see:
* PRIVACY.md – Full privacy policy in plugin directory
* FlxWoo Website – flxwoo.com/privacy
* Contact – [email protected] for privacy inquiries

Note: This plugin is designed with privacy-first principles. All data transmission is necessary for functionality, occurs over encrypted connections, and involves no permanent storage.

Support

Author: Rickey Gu
Website: flxwoo.com
Email: [email protected]
WordPress: wordpress.org/plugins/flx-woo
Demo: demo.flxwoo.com

Need Help?
* Report bugs: WordPress Forums
* Feature requests: WordPress Forums

Automatic Installation

1. Log in to your WordPress admin dashboard
2. Navigate to Plugins → Add New
3. Search for “FlxWoo”
4. Click Install Now then Activate
5. Ensure WooCommerce is installed and active

Manual Installation

1. Download the plugin ZIP file
2. Navigate to Plugins → Add New → Upload Plugin
3. Choose the ZIP file and click Install Now
4. Click Activate Plugin
5. Ensure WooCommerce is installed and active

CORS Configuration:
– ✅ Auto-configured! CORS is automatically allowed for your renderer URL
– ✅ Development auto-allowed: localhost, 127.0.0.1, .local domains (when WP_DEBUG is true)
– ✅ Zero configuration required for most deployments

Configuration (v2.1.0+):

After installation, access the FlxWoo admin interface:

1. Navigate to WP Admin > WooCommerce > FlxWoo
2. Review the Health Dashboard:
   • ✓ Next.js Renderer connectivity status
   • ✓ WooCommerce integration status
   • ✓ Configuration validation status
3. (Optional) Customize Settings:
   • Renderer URL (for custom deployments)
   • Request timeout (1-60 seconds, default: 5s)
   • Cache settings (enable/disable)
   • Development mode (allow HTTP for localhost)
4. Click Refresh Status to verify connectivity
5. Use Quick Actions to test Cart and Checkout pages

Verification:

1. Visit your WooCommerce cart page (/cart)
2. If configured correctly, you’ll see the custom FlxWoo design
3. Check browser console and network tab for errors
4. If Next.js is unavailable, you’ll see the default WooCommerce cart (fallback)
5. Return to Health Dashboard to view system status

Do I need a FlxWoo SaaS subscription?

No subscription required! FlxWoo consists of two components:
1. WordPress plugin (this plugin, open source) – Handles WooCommerce data and API
2. Next.js renderer (FlxWoo SaaS, closed source) – Generates custom HTML

The Next.js renderer is automatically configured and currently FREE during MVP phase. No signup, no payment, no configuration needed – just install the plugin and it works! The renderer is hosted as a SaaS service and cannot be self-hosted, ensuring optimal performance, security updates, and reliability.

Will this break my existing payment gateways?

No! FlxWoo keeps all WooCommerce functionality intact. Payment processing happens server-side through WooCommerce, exactly as before.

What if the Next.js server goes down?

FlxWoo includes automatic fallback. If Next.js is unavailable, customers see the standard WooCommerce cart/checkout. No lost sales.

Does this work with [plugin name]?

If it’s a WooCommerce plugin that modifies checkout, it should work. FlxWoo preserves:
– Payment gateways (Stripe, PayPal, etc.)
– Shipping methods (flat rate, table rate, etc.)
– Tax plugins (TaxJar, Avalara, etc.)
– Coupon plugins (Smart Coupons, etc.)
– Checkout field plugins

How do I customize the design?

The FlxWoo SaaS renderer provides professional, conversion-optimized templates out of the box. For custom design requirements, contact support for enterprise customization options. The Next.js renderer source code is not publicly available.

Is this GDPR compliant?

Yes. FlxWoo includes PII sanitization for logs and uses WordPress’s built-in data handling. The plugin doesn’t store customer data separately.

What’s the performance impact?

Positive! Version 2.0.0 reduced payload size by 30-40% and improved rendering speed by 2-5%. Pages load faster than native WooCommerce.

How do I configure CORS?

You don’t! CORS is automatically configured based on your FLX_WOO_RENDERER_URL constant. For development, localhost and .local domains are auto-allowed.

How do I access FlxWoo settings?

Starting with v2.1.0, FlxWoo includes an admin settings page for easy configuration:

Location: WordPress Admin > WooCommerce > FlxWoo

Available Settings:
* Renderer URL – Configure where customer data is sent for rendering
* Request Timeout – Set maximum wait time (1-60 seconds)
* Cache Settings – Enable/disable caching for performance
* Development Mode – Allow HTTP for localhost testing

Health Dashboard:
* View real-time system status
* Check Next.js renderer connectivity
* Monitor WooCommerce integration
* Verify configuration validity

Quick Access:
* Settings link on Plugins page
* Quick actions: Refresh Status, View Cart, View Checkout

Advanced Configuration:
Override settings in wp-config.php for automated deployments:
define('FLX_WOO_RENDERER_URL', 'https://your-renderer.com');
define('FLX_WOO_RENDERER_TIMEOUT', 10);

Settings priority: Database (Admin Page) > wp-config.php > Default Values

Can I use this with WooCommerce Blocks?

Currently, FlxWoo works with classic WooCommerce cart/checkout shortcodes. WooCommerce Blocks support is on the roadmap and will be added in a future release.

What PHP version is required?

PHP 8.0 or higher. This ensures optimal performance and modern language features.

How do I debug issues or view error logs?

FlxWoo uses structured logging with automatic PII sanitization. To enable debugging:

1. Add to wp-config.php:
   define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

2. Reproduce the issue

3. Check /wp-content/debug.log for entries starting with [FlxWoo]

All logs use a consistent format with error levels (ERROR, WARNING, INFO, DEBUG) and JSON context data. Sensitive information (passwords, credit cards, API keys) is automatically redacted.

For detailed documentation, see ERROR_LOGGING.md in the plugin directory.

How do I report bugs or request features?

Open an issue on WordPress Forums: wordpress.org/support/plugin/flx-woo

Is there a demo site?

Yes! Visit demo.flxwoo.com to see FlxWoo in action.

2.1.0

Release Date: November 20, 2025

Admin Settings & Configuration (November 12, 2025)
* Added WordPress admin interface for configuring FlxWoo
* Location: WP Admin > WooCommerce > FlxWoo
* Settings link added to plugins page for easy access
* Renderer status indicator with real-time health check
* Settings stored in WordPress wp_options table
* Three-tier fallback: Database Settings > wp-config.php Constants > Default Values
* Input validation with user-friendly error messages
* Clean uninstall – removes all plugin data on deletion
* Configurable options: Renderer URL, timeout (1-60s), cache settings, development mode

Health Dashboard (November 20, 2025)
* Added FlxWoo Health Dashboard in WordPress admin
* Overall system health status badge (✓ All Systems Operational / ✗ System Issue Detected)
* Component status monitoring (Next.js Renderer, WooCommerce Integration, Configuration)
* Quick Actions panel (Settings, Refresh Status, View Cart, View Checkout)
* Clean, professional WordPress admin interface with status indicators
* Automatic health check on dashboard page load
* Reuses existing /api/health endpoint infrastructure

Rate Limiting for API Protection (November 20, 2025)
* Added comprehensive rate limiting across Next.js and WordPress components
* Sliding window counter algorithm for accurate rate limiting
* Configured limits: Cart (60/min), Checkout (30/min), Thank You (10/min), Health (120/min)
* Rate limit headers in all responses (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
* GDPR-compliant IP sanitization in logs
* Integration with Sentry for rate limit violation monitoring
* WordPress transient storage for efficient caching

Error Monitoring with PII Protection (November 20, 2025)
* Production-ready error tracking with Sentry.io integration
* Automatic PII sanitization (emails masked as j***@example.com, phones masked except last 4 digits)
* Names, addresses, and sensitive data automatically redacted
* Production-only deployment (auto-disabled in development)
* Context enrichment (WordPress version, WooCommerce version, PHP version)
* Covers 17 critical error points in WordPress plugin
* All Next.js errors logged via centralized logError() function
* Zero overhead in development environments

Files Created:
* WordPress: SettingsManager.php, SettingsPage.php, settings-page.php view
* WordPress: PerformanceDashboard.php, performance-dashboard.php view, performance-dashboard.css
* WordPress: RateLimiter.php, RateLimitHooks.php
* WordPress: SentryHandler.php
* Next.js: rate-limit.ts, sentry-sanitize.ts

Testing & Quality:
* 25 Next.js unit tests for rate limiter (all passing)
* 46 tests for PII sanitization (all passing)
* WordPress PHPUnit tests for rate limiting
* Total: 382+ Next.js tests, comprehensive WordPress test coverage

2.0.0

Release Date: November 2025

Complete Architecture Rewrite with Modern Features

Core Architecture:
* Headless rendering architecture with Next.js
* REST API endpoints (/wp-json/flx-woo/v1/)
* Automatic fallback to WooCommerce templates
* CORS auto-configuration (zero-config for most setups)
* Security headers (CSP, XFO, XSS protection)
* PII sanitization for development logs
* TypeScript type definitions with Zod validation
* Support for cart, checkout, and thank-you pages
* Output buffering for seamless page replacement
* HTML structure validation
* Graceful error handling

Data Optimization:
* Removed 21 redundant fields from API payload (30-40% size reduction)
* Simplified payment gateway data structure (11 fields → 3 fields)
* Simplified shipping method data structure (7 fields → 3 fields)
* Streamlined checkout field metadata (10 properties → 7 properties)
* Optimized JSON payload for faster transmission

Features (Priority 1 – Critical):
* Applied coupons display with discount details and badges
* Cart fees support (gift wrapping, handling fees, etc.)
* WooCommerce notices (error, success, info messages)
* Minimum order amount validation with warnings
* Disabled checkout button when minimum not met

Features (Priority 2 – Important):
* Stock status warnings on cart items (“Only X left in stock!”)
* Out of stock indicators for unavailable products
* Product variation attributes display (“Color: Red, Size: Large”)
* Cross-sells section on cart page (4 products, responsive grid)
* Enhanced order summary with variation details

Code Optimization:
* Added 10 helper methods across 3 core files
* Added 9 class constants for configuration
* Eliminated ~235 lines of code duplication
* Refactored main checkout method from 237 lines to 72 lines (70% reduction)
* Performance improvement: 2-5% faster rendering
* Caching optimization for database queries

REST API Enhancements:
* Site info endpoint includes WooCommerce currency settings
* Site info endpoint includes date/time format preferences
* Checkout response includes order summary (email, total, coupons)
* Enhanced error responses with field-level validation

Template Updates:
* Cart page: Coupon badges, fees display, stock warnings, variation attributes, cross-sells
* Checkout page: Error/success notices, minimum order warnings, disabled button states
* Thank you page: Variation attributes for order items

Documentation:
* Enhanced Constants.php with comprehensive inline comments
* Added production deployment examples
* Improved developer experience with clear configuration guidance
* Comprehensive readme.txt for WordPress.org submission

Files Modified:
* /src/Data/UserContext.php – Data aggregation and helper methods
* /src/Rest/RestEndpoints.php – API endpoints and validation
* /src/Renderer/HeadlessRender.php – Rendering logic and HTML validation
* /src/Constants/Constants.php – Configuration documentation
* All TypeScript types and Zod schemas updated

1.0.0 – 1.4.0

Release Date: October 2024 – November 2024

• Initial development and prototyping
• Various experimental features
• Early architecture exploration