formipay/MIGRATION_STRATEGY.md

Formipay — Vue to React Migration Strategy

Date: April 18, 2026 Context: Phase 2 — React Admin Foundation

---

Overview

This document explains how to approach the existing Vue.js code in Formipay during the migration to React admin panels.

Key Principle: We are NOT doing a "rewrite everything at once" approach. Vue and React will coexist during Phase 2, with Vue being removed incrementally as React replacements are shipped.

---

Current Vue.js Usage Inventory

Type	Location	Purpose	Replacement Phase
WPCFTO Framework	vendor/	Settings form builder (repeater, fields, etc.)	F2.8 (Global Settings)
Custom Vue 2 App	admin/assets/js/admin-product-editor.js	Product variation pricing table	F2.9 (Product Editor)
Partial Vue Editor	admin/assets/vue/ (if exists)	Form builder canvas	F2.4 (Form Builder)

---

Migration Strategy

Phase 1: Coexistence (Current State)

┌─────────────────────────────────────────────┐
│  Admin Pages                                  │
├─────────────────────────────────────────────┤
│  Forms     │ Products  │ Orders │ Settings    │
│  WPCFTO    │ WPCFTO    │ WPCFTO  │ WPCFTO       │
│  + Vue     │ + Vue     │ (none)  │ + Vue        │
│            │ (custom)  │         │              │
└─────────────────────────────────────────────┘

Status: All pages working. WPCFTO handles forms, custom Vue handles product variations.

---

Phase 2: Incremental React Rollout

Week 3: Build pipeline + React infrastructure. Vue untouched.

Week 4: React Form Builder replaces WPCFTO form editor.

Forms: WPCFTO/Vue → React ✅
Products: WPCFTO + custom Vue → unchanged
Orders: (none) → React ✅
Settings: WPCFTO → unchanged

Week 5: React Order Management (no Vue to touch).

Orders → React ✅

Week 6: React Global Settings replaces WPCFTO.

Settings: WPCFTO → React ✅
Products: WPCFTO + custom Vue → unchanged

After Week 6: WPCFTO framework can be fully removed. Only custom Vue remains.

---

Product Editor Migration (F2.9)

The custom Vue app in admin-product-editor.js is the last Vue piece to migrate.

Current Features (Must Recreate in React)

Feature	Complexity	Notes
Multi-currency flat pricing	Medium	Show all currencies as columns when enabled
Multi-currency expanded mode	High	Inner tables per variation row
Dynamic rows from attribute repeater	High	Syncs with WPCFTO repeater in real-time
Decimal digits per currency	Medium	Step values calculated from currency config
Required field validation	Low	Default currency must have price
Real-time JSON update to hidden input	Medium	product_variation_variables hidden field
SweetAlert2 error dialogs	Low	Uses existing window.Swal or custom alert

Implementation Approach

Option A: Recreate from Scratch (Recommended)

1. Read current Vue code logic — understand the data flow
2. Build React component — VariationPricingTable.jsx
   • Use @tanstack/react-table for the table
   • Use @wordpress/components for form inputs (TextControl, etc.)
   • State management via React hooks (useState, useEffect)
3. Data sync layer — same API endpoint get_product_variables
4. Validation logic — port findFirstMissingDefault() to React

Pros: Clean React code, modern patterns, better type safety
Cons: Requires careful testing to match all edge cases

Option B: Vue-in-React Wrapper (Not Recommended)

Wrap the existing Vue app in a React component using a library like vue-react-wrapper.

Pros: Faster, less risky
Cons: Technical debt, adds bundle size, mixing paradigms

Recommendation: Option A — rewrite in React. The logic is well-contained (~500 lines) and rewriting gives us clean, maintainable React code.

---

Migration Checklist for F2.9

When implementing the React Product Editor:

• Read and document current Vue variation table behavior
• Create src/admin/pages/Products/VariationPricingTable.jsx
• Implement multi-currency flat pricing mode
• Implement multi-currency expanded mode (inner tables)
• Implement attribute repeater sync (MutationObserver or polling)
• Implement decimal digits per currency step calculation
• Implement required field validation (default currency)
• Implement real-time JSON update to hidden product_variation_variables input
• Add SweetAlert2 or equivalent for validation errors
• Test with various currency configurations
• Test with existing products (data migration)
• Remove old Vue script enqueuing from Product page
• Remove Vue dependency if no longer used elsewhere

---

Data Compatibility

The React component must read/write the same data format as the Vue app:

Hidden input format (product_variation_variables):

[
  {
    "key": "Red|||Large",
    "name": "Red - Large",
    "stock": "",
    "weight": 0,
    "active": true,
    "prices": [
      {
        "currency": "USD:::United States Dollar:::$",
        "regular_price": "29.99",
        "sale_price": "24.99",
        "currency_decimal_digits": 2
      }
    ]
  }
]

API endpoint (already exists):

// Product.php - add this if not present
add_action('wp_ajax_get_product_variables', [$this, 'ajax_get_product_variables']);

---

Testing Strategy

1. Unit Tests: Test variation price calculation logic in isolation
2. Integration Tests: Test loading/saving variations via AJAX
3. Manual Tests:
   • Create product with variations
   • Test multi-currency flat mode
   • Test multi-currency expanded mode
   • Test validation (missing default price)
   • Test attribute repeater sync
   • Test editing existing products (data compatibility)

---

Rollback Plan

If React version has critical bugs:

1. Keep Vue version as fallback
2. Add feature flag in settings: "Use React Product Editor (beta)"
3. Default to Vue, allow opting into React
4. Fix React, then make it default

---

Notes

• No Vue Router used — the Vue app is a simple mount, no routing to worry about
• No Vuex — state is local component state + hidden input sync
• jQuery dependency — the Vue app uses jQuery for DOM selection ($('#product-variables-table'). React version should eliminate this.
• Timing: WPCFTO removal happens after Global Settings (F2.8), but Product Editor Vue app is independent — can be migrated anytime after Week 3.

---

End of Migration Strategy.